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.273 2007-04-04 23:42:25 vorlon 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, Frans Pop (current), Andreas Barth (current), Javier
        Fern&aacute;ndez-Sanguino Pe&ntilde;a (current), Steve Langasek
        (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 primary 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
        release to the current release and finally to inform users of known potential
        issues they could encounter when upgrading to or using the
        &releasename; 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 the version you are reading is more than a
        month old<footnote>as listed on the front page of the PDF version and in
        the footer of the online HTML version</footnote>, you might wish to obtain
        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 and upgrade to
        &oldreleasename; first.</p>

        <sect id="bug_reports"><heading>Reporting bugs on this document</heading> 

          <p>We have attempted to test all the different upgrade steps
          described in this document and we have also tried to anticipate all
          the possible issues our users might encounter.</p>

          <p>Nevertheless, if you think you have found any bug in this
          documentation (incorrect information or information that is missing),
          please file a bug in the <url id="&url-bts;" name="bug tracking
          system"> against the <package>release-notes</package> package.</p>

       </sect>

        <sect id="upgrade_reports"><heading>Contributing upgrade reports</heading> 
        <p>We welcome any information from users related to upgrades from
        &oldreleasename; to &releasename;. If you are willing to share information
        please file a bug in the <url id="&url-bts;" name="bug tracking system">
        against the <package>upgrade-reports</package> package with your results.</p>

        <p>Please provide the following information when submitting your upgrade report:

        <list>

<!-- TODO: any more things to add here? -->
            <item><p>The status of your package database before and after the
            upgrade: <prgn/dpkg/'s status database available at
            <file>/var/lib/dpkg/status</file> and <prgn/aptitudes/'s package
            state information, available at
            <file>/var/lib/aptitude/pkgstates</file>. You should have made a
            backup before the upgrade as described at <ref id="data-backup">,
            but you can also find backups of this information in
            <file>/var/backups</file>.</p></item>

            <item><p>Session logs using <package>script</package>, as described in
            <ref id="record_session">.</p></item>

            <item><p>Your aptitude logs, available at <file>/var/log/aptitude</file>.</p></item>

        </list></p>

        <p>Note: you should take some time to review and remove any sensitive and/or confidential
        information from the logs before including them in a bug report as the information
        will be published in a public database.

        </sect>

        <sect id="sources"><heading>Sources for this document</heading> 
          <p>This document is generated using <package>debiandoc-sgml</package>.
          Sources for the Release Notes
          are available in the CVS repository of the <em>Debian Documentation Project</em>.
          You can use the <url id="&url-cvs-release-notes;" name="web
          interface"> to access its files individually through the web and see
          their changes. For more information on how to access the CVS please
          consult the <url id="&url-ddp-cvs-info;" name="Debian Documentation Project CVS pages">.
          </p>

        </sect>
<!--
        <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.
<![ %amd64 [
        Upgrading from this unofficial version should be possible using these
        Release Notes, but is not officially supported by Debian.
]]>
        </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>
]]>

<![ %arm [
        <sect id="new-arch"><heading>What's new for &arch-title;?</heading>
          <p>RiscPC (RPC) support is incomplete and will be removed after etch.
          While a kernel for RiscPC is still provided in etch, the installer
          doesn't support this system.</p>

          <p>Support for Intel's IXP4xx platform has been added.  The installer
          includes support for the Linksys NSLU2, a small and inexpensive device
          which allows the usage of attached storage through USB.  More
          information about Debian on the NSLU2 can be found at
          <url id="http://www.cyrius.com/debian/nslu2/">.</p>

          <p>Support has also been added for Intel's I/O Processor (IOP) platform.
          Specifically, &debian; &release; supports IOP 32x based devices.  Two Network
          Attached Storage (NAS) devices based on an IOP chip are supported in
          the installer: the GLAN Tank from IO-Data and the Thecus N2100.  See
          <url id="http://www.cyrius.com/debian/iop/">.</p>
        </sect>
]]>

<![ %mips-mipsel [
        <sect id="new-arch"><heading>What's new for &arch-title;?</heading>
<![ %mipsel [
          <p>DECstation support is incomplete and untested in etch and will be
          removed completely after this release.  This includes both DECstation
          variants previously supported in Debian, r3k-kn02 and r4k-kn04.</p>

          <p>Installations on MIPS based Cobalt machines (Qube 2700, RaQ1, Qube2,
          RaQ2) are now possible without the use of a serial console.  By
          default, installations on Cobalt are now done via SSH.  See
          <url id="http://www.cyrius.com/debian/cobalt/"> for more information.</p>
]]>
<![ %mips [
          <p>Support for SGI's IP32 platform has been added.  The IP32 platform
          consists of SGI O2 machines with R5000, R5200 or RM7000 processors.
          Installation is possible via frame buffer or the serial console.</p>
]]>
          <p>Support for Broadcom's SB1A evaluation board BCM91480B ("BigSur"),
          which is based on the BCM1480 quad-core chip, has been added, both to
          the kernel and the installer.  This board is supported both in little
          and big endian mode.</p>

          <p>Support for a Qemu machine has been added. The Qemu/MIPS machine
          emulates a classic ISA PC style machine with a MIPS 4Kc CPU.</p>
        </sect>
]]>

<![ %powerpc [
        <sect id="new-arch"><heading>What's new for &arch-title;?</heading>
          <p>This release adds support for 64bit PowerPC architectures (IBM
          pSeries, Apple G5 powermacs). Support for the Apple Apus subarchitecture
          has been dropped; the Apple Nubus subarchitecture is also not supported.</p>
        </sect>
]]>

<!--
          <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 (jfs): numbers could be entities so that updating them was easier, like
     in the FAQ -->
<!-- TODO: Numbers need to be reviewed, these values have been obtained
     using the changes-release script -->           
           <p>This new release of Debian again comes with a lot more software
           than its predecessor &oldreleasename;; the distribution includes
           over &packages-new; new packages, for a total of over &packages-total; packages. Most
           of the software in the distribution has been updated: over &packages-updated;
           software packages (this is &packages-update-percent;% of all packages in &oldreleasename;).
           Also, a significant number of packages (over &packages-removed;, &packages-removed-percent;% of the
           packages in &oldreleasename;) 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 X.Org, 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 several desktop applications and environments.
           Among others it now includes the desktop environments GNOME
           2.14<footnote>with some modules from GNOME 2.16</footnote>, KDE 3.5.5a,
           and Xfce 4.4. Productivity applications have also been upgraded,
           including the office suites OpenOffice.org 2.0.4a and KOffice 1.6 as
           well as GNUcash 2.0.5, GNUmeric 1.6.3 and Abiword 2.4.6.</p>

           <p>Updates of other desktop applications include the upgrade to
           Evolution 2.6.3 and Gaim 2.0.  The Mozilla suite has also been updated,
           with a rename of the main programs: <prgn>iceweasel</prgn>
           (version 2.0.0.2) is the unbranded <prgn>Firefox</prgn> web browser
           and <prgn/icedove/ (version 1.5) is the unbranded <prgn/Thunderbird/
           mail client.</p>

           <p>Among many others, this release also includes the following software
           updates:</p>

           <p><list>

           <item>the GNU C library, version 2.3.6</item>

           <item>the GNU Compiler Collection 4.1 as default compiler</item>

           <item>language interpreters: PHP 5.2, Python 2.4</item>

           <item>server software:

           <p><list>
           <item>e-mail servers: Exim 4.63 (default email server
           for new installations), Postfix 2.3, Courier 0.53, Cyrus 2.2.</item>

<!-- TODO: Cherokee, lighttpd, and Tomcat 5 are NEW -->
<!-- Note: No significant changes for Roxen4, Boa, and thttpd  -->
           <item>web servers: Apache 2.2, fnord 1.10</item>

           <item>database servers: MySQL 5.0.32, PostgreSQL 8.1</item>

           <item>the OpenSSH server, version 4.3</item>

           <item>name servers: Bind 9.3, maradns 1.2</item>

           <item>directory server: OpenLDAP 2.3</item>

<!-- FIXME (JFS): List other server software? RADIUS? Streaming ? -->
           </list></p>

           </list></p>


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

<!-- FIXME: Note on LSB support? (3.1?) -->

        <sect1 id="pkgmgmt"><heading>Package management</heading>

<!-- FIXME (vorlon): is aptitude news for etch, does it belong here? -->
           <p><prgn/aptitude/ is the preferred program for package management
           from console.
           <prgn/aptitude/ supports most command line operations of <prgn/apt-get/
           and has proven to be better at dependency resolution than <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>For &releasename; an advanced conflict resolving mechanism has been
           implemented in <prgn/aptitude/ that will try to find the best solution
           if conflicts are detected because of changes in dependencies between
           packages.</p>

<!-- FIXME: More content needed here? -->
           <p><em/Secure APT/ is now available in &releasename;. This feature adds
           extra security to &debian; systems by easily supporting strong
           cryptography and digital signatures to validate downloaded packages.
           This release includes the <prgn/apt-key/ tool for adding new keys to
           apt's keyring, which by default includes only the current Debian archive
           signing key, provided in the <package>debian-archive-keyring</package>
           package.</p>

           <p>In its default configuration, <prgn/apt/ will now warn if packages
           are downloaded from sources that are not authenticated.  Future releases
           might force all packages to be verified before downloading them.
           Administrators of unofficial apt repositories are encouraged to
           generate a cryptographic key and sign their Release files, as well
           as providing a secure way to distribute their public keys.</p>

           <p>For more information please read <manref name="apt" section="8">, the
           <url
           id="http://www.debian.org/doc/manuals/securing-debian-howto/ch7#s-deb-pack-sign"
           name="Package signing in Debian"> chapter of the <em/Securing Debian
           Manual/ and the <url id="http://wiki.debian.org/SecureApt"
           name="Debian Wiki">.</p>

           <p>Another feature that was added in <prgn/apt/ is the ability to
           download only the changes in <file/Packages/ files since your last
           update. More about this feature in <ref id="apt-pdiff">.</p>

        </sect1>
        <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 now uses a <tt/.debian.org/ address<footnote>
           The old <tt/volatile.debian.net/ address will also remain valid for
           the time being. </footnote>. 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="system-changes"><heading>System improvements</heading>

       <p>There have been a number of changes in the distribution that will
       benefit new installations of &releasename;, but may not be automatically
       applied on upgrades from &oldreleasename;. This section gives an
       overview of the most relevant changes.
       </p>

       <p><taglist>

<!-- Bug #301138, fixed in etch -->
       <tag>Priority for basic development packages lowered</tag>
       <item><p>A number of development packages that used to be priority
       <em/standard/ are now priority <em/optional/, which means they will
       no longer be installed by default.
       This includes the standard C/C++-compiler, <package>gcc</package>,
       as well as some other software (<package>dpkg-dev</package>,
       <package>flex</package>, <package>make</package>) and development
       headers (<package>libc6-dev</package>,
       <package>linux-kernel-headers</package>).</p>
<!-- TODO: Point to the bug report for the full list of packages in case
     users want to remove them ? -->
       <p>If you do wish to have these packages on your system, the easiest way
       to install them is by installing <package/build-essential/, which will
       pull in most of them.</p>
       </item>

       <tag>SELinux priority standard, but not enabled by default</tag>
       <item><p>The packages needed for SELinux support have been
       promoted to priority <em/standard/. This means that they will be
       installed by default during new installations. For existing systems
       you can install SELinux using:
       <example>
# aptitude install selinux-basics
       </example></p>

       <p>Note that SELinux support is <em/not/ enabled by default. Information
       on setting up and enabling SELinux can be found on the
       <url id="&url-wiki-selinux;" name="Debian Wiki">.
       </p></item>

       <tag>New default inet superdaemon</tag>
       <item><p>The default inet superdaemon for &releasename; is
       <package>openbsd-inetd</package> instead of <package>netkit-inetd</package>.
       It will not be started if no services are configured, which is true by
       default. The new default daemon will be installed automatically on
       upgrade.
       </p></item>

       <tag>Default <prgn/vi/ clone changed</tag>
       <item><p>The <prgn/vi/ clone installed by default is now a compact version
       of <prgn/vim/ (<package/vim-tiny/) instead of <package/nvi/.</p></item>

       <tag>Changes in default features for <tt>ext2</tt>/<tt>ext3</tt></tag>
       <item><p>New ext2 and ext3 file systems will be created with features
       <em/dir_index/ and <em/resize_inode/ enabled by default. The first
       feature speeds up operations on directories with many files; the
       second makes it possible to resize a file system on-line (i.e. while it
       is mounted).</p>
       <p>Users upgrading from &oldreleasename; could consider adding the
       <em/dir_index/ flag manually using <prgn/tune2fs/<footnote>
       The flag <em/filetype/ should already be set on most file systems, except
       possibly on systems installed before &oldreleasename;.
       </footnote>; the <em/resize_inode/ flag cannot be added to an existing
       file system. It is possible to check which flags are set for a file
       system using <tt/dumpe2fs -h/.</p></item>

<!-- TODO: Add for lenny, link to utf8-migration-tool, which is right now not
     available for etch -->
       <tag>Default encoding for &releasename; is UTF-8</tag>
       <item><p>The default encoding for new &debian; installations is UTF-8. A
       number of applications will also be set up to use UTF-8 by default.</p>
       <p>Users upgrading to &releasename; that wish to switch to UTF-8 will
       need to reconfigure their environment and locale definitions. The
       system-wide default can be changed using <tt/dpkg-reconfigure locales/;
       first select a UTF-8 locale for your language and country and then
       set that as default. Note that switching to UTF-8 means that you will
       probably also need to convert existing files from your previous
       (legacy) encoding to UTF-8.</p>
       <p>The package <package/utf8-migration-tool/ contains a tool that may
       help the migration, however that package is only available in unstable
       as it was not ready in time for &releasename;. Making a backup of
       your data and configuration before using the tool is strongly
       recommended.</p>
       <p>Note that some applications may not yet work correctly in a UTF-8
       environment, mostly due to display issues.</p></item>

       </taglist></p>

      <p>The <url id="http://wiki.debian.org/Sarge2EtchUpgrade"
      name="Debian Wiki"> has some additional information about changes between
      &oldreleasename; and &releasename;.</p>

        </sect>

      <sect id="kernel-changes"><heading>Major kernel-related changes</heading>

        <p>&debian; &release; ships with kernel version &kernelversion; for all
        architectures; the release is still mostly
<!-- JFS: Needed because of the cross ref, build errors will appear in some
     architectures otherwise -->
<![ %defaulted-2.4 [
        <footnote>Some individual
        packages may no longer work correctly with a 2.4 kernel; see
        <ref id="incompatible-2.4">.</footnote>
]]>
        compatible with 2.4 kernels, but
        Debian no longer provides or supports 2.4 kernel packages.</p>

        <p>There have been major changes both in the kernel itself and in the
        packaging of the kernel for Debian. Some of these changes complicate
        the upgrade procedure and can potentially result in problems while
        rebooting the system after the upgrade to &releasename;. This section
        gives an overview of the most important changes; potential issues and
        information on how to work around them is included in later chapters.</p>

<![ %defaulted-2.4 [
        <p>If you are currently using a 2.4 kernel, you should read
        <ref id="upgrade-to-2.6"> carefully.</p>
]]>

      <sect1 id="kernel-packaging"><heading>Changes in kernel packaging</heading>

        <p><taglist>
        <tag>Kernel packages renamed</tag>
        <item><p>All Linux kernel packages have been renamed from <tt/kernel-*/
        to <tt/linux-*/ to clean up the namespace. This will make it easier to
        include non-Linux kernels in Debian in the future.</p></item>

<![ %i386 [
        <tag>Flavor "386" replaced with "486"</tag>
        <item><p>As support for 80386 processors was dropped with &oldreleasename;,
        the 386 kernel flavor has now been dropped as well and replaced by a
        new 486 flavor.</p></item>
]]>
<![ %amd64 [
        <tag>Single generic kernel for &arch-title;</tag>
        <item><p>In &oldreleasename; there were separate kernel flavors for
        different processor families of this architecture. Because of changes
        in the kernel which will
        automatically optimize the kernel for the processor(s) in the system,
        there is no longer any real need for seperate kernel flavors.</p></item>
]]>

<![ %i386-amd64-ia64 [
        <tag>Standard kernels have SMP abilities</tag>
        <item><p>Multiprocessor systems no longer require an <tt/*-smp/ flavor of the
        Linux kernel. For &arch-title;, <tt/linux-image/ packages without the <tt/-smp/
        suffix support both uniprocessor and multiprocessor systems.
<![ %i386 [
        (The one exception is the 486 flavor, which only supports a single
        processor.)
]]>
        </p></item>
]]>

<![ %mips [
        <tag>r5k-ip22 kernel flavor dropped</tag>
        <item><p>The kernel image for IP22 machines with an R5000 CPU has been
        dropped because the r4k-ip22 image now supports IP22 machines with either
        an R4x000 or an R5000 CPU.</p></item>
]]>
        </taglist></p>

        <p>Where possible, dummy transition packages that depend on the new packages
        have been provided for the dropped packages.</p>

      </sect1>

      <sect1 id="kernel-initrd"><heading>New utilities to generate initrds</heading>

<![ %no-initrd [
        <p>The Debian kernel image packages for &arch-title; do not require an
        initrd for booting the system. This means that the information in this
        section may not be relevant for you, but is still included for
        reference.</p>
]]>
        <p>
<![ %uses-initrd [
        The Debian kernel image packages for &arch-title; require an initrd
        for booting the system.
]]>
        Because of changes in the kernel, the utility used to generate initrds in
        &oldreleasename;, <package/initrd-tools/ can no longer be used and has been
        deprecated. Two new utilities have been developed that replace it:
        <package/initramfs-tools/ and <package/yaird/. The concepts behind the new
        utilities are very different; an overview is available on the
        <url id="http://wiki.debian.org/InitrdReplacementOptions" name="Debian Wiki">.
        Both will generate an initrd using the <em/initramfs/ file system, which is
        a compressed <prgn/cpio/ archive.
        The default and recommended utility is <package/initramfs-tools/.
        </p>

<![ %uses-initrd [
        <p>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 Debian kernel,
        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>

        <p>The package <package/initrd-tools/ is still included in &releasename;
        because it is needed for upgrades from &oldreleasename;. It will
        be dropped for the next release.</p>
]]>

      </sect1>

      <sect1 id="kernel-devfs"><heading>Dynamic <file>/dev</file> management</heading>

        <p>&releasename; kernels no longer provide support for <tt>devfs</tt>.</p>

        <p>The replacement for <tt>devfs</tt> is <package/udev/.
        <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,
        based on events generated by the kernel. <prgn/udev/ is a lot more
        versatile than <tt/devfs/ and offers services that are used by other
        packages like <package/hal/ (hardware abstraction layer).</p>

<![ %uses-initrd [
        <p>If you install a Debian kernel image, <package/udev/ will be installed
        by default as <package/initramfs-tools/ depends on it.</p>
        <p>You can avoid installing <package/udev/ by compiling a custom non-modular
        kernel or by using an alternative initrd generator, such as <package/yaird/.
        However, <package/initramfs-tools/ is the recommended initrd generator.
]]>

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

      <chapt id="installing"><heading>Installation System</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; can be found together with the
        Installation Guide 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 for a list of known issues.</p>

<![ %alpha [
        <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, the recommended way to install &releasename; is to first install
        a (minimal) woody system, the upgrade to &oldreleasename; and finally to
        &releasename;.  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="sparc_illegal_instruction"><heading>Issues with booting on &arch-title;</heading>

        <p>It has been reported by several users that the installation CD
        fails to boot successfully upon the '<tt>boot cdrom</tt>' PROM
        command, displaying the error '<tt>Illegal Instruction</tt>'.</p>

        <p>The apparent explanation for this problem is that it doesn't work
        because the machine had previously been rebooted from Solaris.
        The workaround is to power the machine off fully, and then boot it
        directly into the installation CD.</p>

        <p>The problem was reported by users of various systems (namely,
        Enterprise 450, Blade 2000, Fire V240, Enterprise 250 and Blade 100
        at the time of writing), so it is believed to be generic. Please
        let us know if you observe similar issues with your hardware.</p>

      </sect>
]]>

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

           <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 available from the
           Debian Installer'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>Previously, the installation was 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>

<!-- FIXME (vorlon): is this true for /all/ languages? -->
             <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 KOI-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 file systems.
             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
             file systems (except <file>/boot</file>) as logical volumes.</p></item>

<![ %g-i [
             <tag>Graphical user interface</tag>
             <item>
<![ %i386-amd64 [
             <p>If you prefer a graphical user interface, try booting
             the installer with <tt/installgui/.</p>
]]>

<![ %powerpc [
             <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>
]]>

             <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>The major advantage of the graphical user interface is that it
             supports more languages than the regular user interface (newt).
             Information about the graphical installer and the most important
             differences between the graphical and regular installer are documented
             in an appendix in the installation guide.</p>
             <p>Note: the graphical user interface is not available for all
             architectures.</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>

             <tag>Cryptographic verification of downloaded packages</tag>
             <item><p>Packages downloaded with the installer are
             now cryptographically checked using <prgn/apt/,
             making it more difficult to compromise a system being
             installed over the network.</p></item>

             <tag>Simplified mail configuration</tag>
             <item><p>If the "standard system" is installed, the installer sets up
             a basic configuration for the system's mail server which will only
             provide for local e-mail delivery. The mail server will be unavailable
             to other systems connected to the same network. If you want to
             configure your system to handle e-mail not local to the system (either
             to send e-mail or to receive it), you will have to reconfigure the mail
             system after installation.</p></item>

             <tag>Desktop selection</tag>
             <item><p>The installation system will install 
             a GNOME desktop as the default desktop if the user asks for one.</p>
             <p>However, users wishing to install alternate desktop environments
             can easily do so by adding boot parameters:
             <tt>tasks="standard, kde-desktop"</tt> for KDE and
             <tt>tasks="standard, xfce-desktop"</tt> for Xfce. Note that this
             will not work when installing from a full CD image without using
             a network mirror as an additional package source; it will work
             when using a DVD image or any other installation method.</p>
             <p>There are also separate CD images available that install the
             KDE or Xfce desktop environment by default.</p></item>

<![ %not-s390 [
             <tag>New languages</tag>
             <item><p>Thanks to the huge efforts of translators, Debian can
             now be installed in 47 languages using the text-based
             installation user interface. This is six languages more
             than in &oldreleasename;. Languages added in this release include
             Belarusian, Esperanto, Estonian, Kurdish, Macedonian,
             Tagalog, Vietnamese and Wolof.
             Due to lack of translation updates, two languages have been dropped
             in this release: Persian and Welsh.</p>
<![ %g-i [
             <p>If the graphical user interface is used, an additional eleven
             languages are supported. These languages can only be selected
             using this installer as their character sets cannot be presented
             in a non-graphical environment. The new languages are:
             Bengali, Dzongkha, Gujarati, Hindi, Georgian, Khmer, Malayalam,
             Nepali, Punjabi, Tamil and Thai.</p>
]]>
             <p>Users that do not wish to use any locale can now select
             <em/C/ as their preferred locale in the installer's language
             selection.
             More information on language coverage is available at the
             <url id="&url-d-i-i18n;" name="d-i languages list">.
             </p></item>

             <tag>Simplified localization and timezone selection</tag>
             <item><p>Configuration of language, countries and timezones
             has been simplified to reduce the amount of information
             needed from the user. The installer will now guess
             what the system's country and timezone is based on the
             language selected, or will provide a limited selection
             if it cannot. Users can still introduce obscure 
             combinations if need be.</p></item>

      <tag>Improved system-wide localization</tag>
      <item><p>Most of the internationalization and localization tasks that
      were previously handled by the <package>localization-config</package> tool are now
      included in the stock Debian installer or in packages themselves. This
      means that selection of a language will automatically install packages
      necessary for that language (dictionaries, documentation, fonts...) in both
      standard and desktop environments. Configuration that is no longer
      handled automatically includes the papersize configuration and some
      advanced X Windows keyboard settings for some languages.</p>
      <p>Note that language-specific packages will only be installed
      automatically if they are available during the installation.</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 further 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>

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

        <p>The installation system will again offer
        to install the <package/popularity-contest/ package. This package was not 
        installed by default in &oldreleasename; but it was installed in older releases.</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,
        helping to 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
          important to know about before you begin.</p>

       <sect1 id="data-backup"><heading>Back up any data or configuration information</heading>
 
          <p>Before upgrading your system, it is strongly recommended that
          you make a full backup, or at least back up 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 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>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>

       <sect1><heading>Inform users in advance</heading>

          <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. </p>
          
          <p>If you wish to take extra precautions, back up or
          unmount users' partitions (<file>/home</file>) before upgrading.</p>

<!-- JFS: Not true in etch, maybe for lenny?
          <p>A reboot will not normally be necessary, unless you also plan to
          upgrade your kernel.</p>
-->
          <p>You will probably have to do a kernel upgrade when upgrading to 
          &releasename;, so a reboot will normally be necessary. Typically,
          this will be done after the upgrade is finished.</p>

       </sect1>

       <sect1 id="upgrade_preparations"><heading>Prepare a safe environment for the upgrade</heading>

          <p>The 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>In order to gain extra safety margin when upgrading remotely, we
          suggest that you run upgrade processes in the virtual console provided by
          the <prgn/screen/ program, which enables safe reconnection and ensures
          the upgrade process is not interrupted even if the remote connection
          process fails.</p>

<!-- JFS: probably can be removed for lenny -->
          <p>If you are upgrading remotely via an <prgn/ssh/ link it is highly
          recommended that you take the necessary precautions to be able to
          access the server through a remote serial terminal. There are chances
          that, after upgrading the kernel and rebooting, some devices will
          be renamed (as described in <ref id="device-reorder">) and you will
          have to fix the system configuration through a local console. Also,
          if the system is rebooted accidentally in the middle of an upgrade
          there are chances you will need to recover using a local console.</p>
<!-- END - remove for lenny -->
          
          <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? -->
          <!-- (vorlon) haha, no, gdm is not; I had that thought, and tested a gdm
               restart on my live session ;) -->
       </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 <package/glibc/.
          This should be done before starting the upgrade.
          It is recommended that you directly upgrade to the 2.6.8 kernel available
          in &oldreleasename;, instead of upgrading to a 2.4 kernel.
          </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 third-party
        packages.
<!-- vorlon: remove for lenny -->
        In particular, there are known problems with third-party packages
        which install programs under <file>/usr/X11R6/bin/</file> causing problems
        with upgrades due to the X.org transition (<ref id="xorg">).
<!-- -->
        For greatest reliability of the upgrade process, you may wish to remove
        third-party packages from your system before you begin upgrading.</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>Review actions pending in package manager</heading>

          <p>In some cases, the use of <prgn/apt-get/ for installing packages instead
          of <prgn/aptitude/ might make <prgn/aptitude/ consider a package as
          "unused" and schedule it for removal. In general, you should make sure 
          the system is fully up-to-date and "clean" before proceeding with
          the upgrade.</p>

          <p>Because of this you should review if there are any pending actions
          in the package manager <prgn/aptitude/. If a package is scheduled
          for removal or update in the package manager, it might negatively impact
          the upgrade procedure. Note that correcting this is only possible if your
          <file/sources.list/ still points to <em/&oldreleasename/; and not to
          <em/stable/ or <em/&releasename;/; see <ref id="old-sources">.</p>

          <p>To do this, you have to run <prgn/aptitude/'s user interface and
          press 'g' ("Go"). If it shows any actions, you should review them and
          either fix them or implement the suggested actions. If no actions are
          suggested you will be presented with a message saying "No packages are
          scheduled to be installed, removed, or upgraded".</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 id="package_status"><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:
          <example>
# aptitude hold <var>package_name</var>
          </example>
          Replace <tt/hold/ with <tt/unhold/ to unset the "hold" state.
          </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 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>

<!-- JFS: This section should be probably removed for lenny -->
        <sect id="handle-conflict"><heading>Manually unmarking packages</heading>

        <p>To prevent <prgn/aptitude/ from removing some packages that were pulled
        in through dependencies, you need to manually unmark them as <em/auto/
        packages. This includes OpenOffice and Vim for desktop installs:
<!-- This is a no-op if none of them are installed -->
<example>
# aptitude unmarkauto openoffice.org vim  
</example></p>

<!-- JFS: This cannot be in the same line as above since it produces an ugly output if 
     you just have 2.4 kernels installed -->
        <p>And 2.6 kernel images if you have installed them using a kernel metapackage:

<example>
# aptitude unmarkauto $(dpkg-query -W 'kernel-image-2.6.*' | cut -f1)
</example></p>

        <p>Note: You can review which packages are marked as <em/auto/ in aptitude by running:

<example>
# aptitude search 'i~M &lt;package name&gt;'
</example></p>
        </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>

         </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>". There should not be
          any sources entries pointing to &oldreleasename;. 
          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>

        <sect1 id="record_session"><heading>Recording the session</heading>

          <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 -t 2>~/upgrade-&releasename;.time -a ~/upgrade-&releasename;.script
          </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 -R ~root/upgrade-&releasename;.script</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>

<!-- TODO: Could mention the script I provided in 400725 which is useful if you 
     have not dumped the timing file -->
          <p>If you have used the <em>-t</em> switch for <prgn/script/
          you can use the <prgn/scriptreplay/ program to replay the whole session:
          
          <example>
# scriptreplay ~/upgrade-&releasename;.time ~/upgrade-&releasename;.script
          </example>

          </p>
        </sect1>

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

          <p><example>
# aptitude update
          </example></p>

<!-- JFS: Hopefully this will be fixed in lenny -->
          <p>Running this the first time new sources are updated will print out
          some warnings related to the availability of the sources. These
          warnings are harmless and will not appear if you rerun the command again.
          </p>

        </sect1>

       <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">.  First, 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
       on the file system 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 
       file system 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. Before executing the
       upgrade, you can see this estimate by 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> or <prgn>aptitude
       clean</prgn> will remove all previously downloaded package files.

<!-- 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">).
       Alternatively you can start <prgn/aptitude/ in "visual mode" and find
       obsolete packages under "Obsolete and Locally Created Packages".

       <item>Remove packages taking up too much space, which are not currently 
       needed (you can always reinstall them after the
       upgrade). You can list the packages that take up most of the disk space
       with <prgn/dpigs/ (available in the <package/debian-goodies/ package)
       or with <prgn/wajig/ (running <tt>wajig size</tt>).

<!-- TODO: consider this for lenny
You can list packages that take up most of the disk space with
       <prgn/aptitude/ .  Start <prgn/aptitude/ into "visual mode", select
       "Views" and "New Flat Package List" (this menu entry is available only
       after etch version), press "l" and enter "~i", press "S" and enter
       "~installsize", then it will give you nice list to work with.  Doing
       this after partial upgrade described in <ref id="upgrading_aptitude">
       should give you access to this new feature.
-->

       <item>Temporarily move to another system, or permanently remove, system
       logs residing under <file>/var/log/</file>.

       </list></p>

       <p>Note that in order to safely remove packages, it is advisable to
       switch your <file>sources.list</file> back to &oldreleasename; as
       described in <ref id="old-sources">.</p>

        </sect1>

        <sect1 id="minimal_upgrade"><heading>Minimal system upgrade</heading>

        <p>Because of certain necessary package conflicts between &oldreleasename;
        and &releasename;, running <tt>aptitude dist-upgrade</tt> directly will
        often remove large numbers of packages that you will want to keep.  We
        therefore recommend a two-part upgrade process, first a minimal upgrade to
        overcome these conflicts, then a full <tt>dist-upgrade</tt>.
        </p>

        <p>First, run:
          <example>
# aptitude upgrade
          </example>
        </p>

        <p>This has the effect of upgrading those packages which can be upgraded
        without requiring any other packages to be removed or installed.</p>

        <p>Follow the minimal upgrade with:
          <example>
# aptitude install initrd-tools
          </example></p>

        <p>This step will automatically upgrade <package/libc6/ and
        <package/locales/ and will pull in SELinux support libraries
        (<package/libselinux1/). At this point, some running services will be
        restarted, including <prgn/xdm/, <prgn/gdm/ and <prgn/kdm/. As a
        consequence, local X11 sessions will be disconnected.</p>

        <p>The next step will vary depending on the set of packages that you have
        installed.  These release notes give general advice about which method
        should be used, but if in doubt, it is recommended that you examine the
        package removals proposed by each method before proceeding.</p>
        <p>Some common packages that are expected to be removed include
        <package/base-config/, <package/hotplug/, <package/xlibs/,
        <package/netkit-inetd/, <package/python2.3/, <package/xfree86-common/,
        and <package/xserver-common/.  For a more complete list of packages
        obsoleted in &releasename;, see <ref id="obsolete">.
        </p>

         <sect2 id="minimal_upgrade_desktop"><heading>Upgrading a desktop system</heading>
        <p>This upgrade path has been verified to work on systems with the sarge
        <tt>desktop</tt> task installed.  It is probably the method that will give
        the best results on systems with the <tt>desktop</tt> task installed, or
        with the <tt>gnome</tt> or <tt>kde</tt> packages installed.

        <p>It is probably <em>not</em> the correct method to use if you do not
        already have the <package/libfam0c102/ and <package/xlibmesa-glu/ packages
        installed:
          <example>
# dpkg -l libfam0c102 | grep ^ii
# dpkg -l xlibmesa-glu | grep ^ii
          </example>
        </p>

        <p>If you do have a full desktop system installed, run:
          <example>
# aptitude install libfam0 xlibmesa-glu
          </example></p>

         </sect2>

         <sect2 id="minimal_upgrade_x_server"><heading>Upgrading a system with some X packages installed</heading>
        <p>Systems with some X packages installed, but not the full
        <tt>desktop</tt> task, require a different method.  This method applies in
        general to systems with <package/xfree86-common/ installed, including some
        server systems which have <package/tasksel/ server tasks installed as some
        of these tasks include graphical management tools.  It is likely the
        correct method to use on systems which run X, but do not have the full
        <tt>desktop</tt> task installed.
        <example>
# dpkg -l xfree86-common | grep ^ii
        </example>
        </p>

        <p>First, check whether you have the <package/libfam0c102/ and
        <package/xlibmesa-glu/ packages installed.
          <example>
# dpkg -l libfam0c102 | grep ^ii
# dpkg -l xlibmesa-glu | grep ^ii
          </example>
        </p>

        <p>If you do not have <package/libfam0c102/ installed, do not include
        <package/libfam0/ in the following commandline.  If you do not have
        <package/xlibmesa-glu/ installed, do not include it in the following
        commandline.
          <footnote>This command will determine whether you need libfam0 and
          xlibmesa-glu installed, and auto-select them for you:
          <example>
# aptitude install x11-common \
  $(dpkg-query --showformat '${Package} ${Status}\n' -W libfam0c102 xlibmesa-glu \
    | grep 'ok installed$' | sed -e's/ .*//; s/c102//')
          </example>
          </footnote>

          <example>
# aptitude install x11-common <var>libfam0</var> <var>xlibmesa-glu</var>
          </example>
        </p>

          <p>Note that installing <package/libfam0/ will also install the File Alteration Monitor
          (<package/fam/) as well as the RPC portmapper (<package/portmap/) if
          not already available in your system. Both packages will enable a new
          network service in the system although they can both be configured to
          be bound to the (internal) loopback network device.</p>
         </sect2>

         <sect2 id="minimal_upgrade_server"><heading>Upgrading a system with no X support installed</heading>
        <p>On a system with no X, no additional aptitude install command should be
        required, and you can move on to the next step.
        </p>

         </sect2>

        </sect1>

        <sect1 id="upgrading_kernel"><heading>Upgrading the kernel</heading>

        <p>The <package/udev/ version in &releasename; does not support kernel
        versions earlier than 2.6.15 (which includes &oldreleasename; 2.6.8
        kernels), and the <package/udev/ version in &oldreleasename; will not work
        properly with the latest kernels.  In addition, installing the
        &releasename; version of <package/udev/ will force the removal of
        <package/hotplug/, used by Linux 2.4 kernels.</p>

        <p>As a consequence, the previous kernel package will probably not boot
        properly after this upgrade. Similarly, there is a time window during
        the upgrade in which <package/udev/ has been upgraded but the latest kernel
        has not been installed. If the system were to be rebooted at this point,
        in the middle of the upgrade, it might not be bootable because of
        drivers not being properly detected and loaded.  (See <ref
        id="upgrade_preparations"> for recommendations on preparing for this
        possibility if you are upgrading remotely.)</p>

        <p>Unless your system has the <tt>desktop</tt> task installed, or
        other packages that would cause an unacceptable number of package
        removals, it is therefore recommended that you upgrade the kernel on its 
        own at this point.</p>

          <p>To proceed with this kernel upgrade, run:
          <example>
# aptitude install linux-image-2.6-<var>flavor</var>
          </example>

          See <ref id="kernel-metapackage"> for help in determining which flavor of
          kernel package you should install.</p>

          <p>In the desktop case, it is unfortunately not possible to ensure the
          new kernel package is installed immediately after the new <package/udev/
          is installed, so there is a window of unknown length when your system
          will have no kernel installed with full hotplug support.  See <ref
          id="newkernel"> for information on configuring your system to not depend
          on hotplug for booting.</p>

        </sect1>

<!-- TODO: For lenny, consider restoring the section 'Upgrade aptitude' -->

        <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>
<!-- NOTE (jfs): we have not tested with the -f and with-recommends option -->
          <p><example>
# aptitude 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.</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>

        </sect1>

<!-- JFS: Bug #403496 -->
        <sect1 id="get_signatures"><heading>Getting package signatures</heading>

          <p>After the upgrade, with the new version of <prgn/apt/ you can now
          update your package information, which will include the new package
          signature checking mechanism:</p>
          <p><example>
# aptitude update
          </example></p>

          <p>The upgrade will have already retrieved and enabled the signing
          keys for Debian's package archives. If you add other (unofficial)
          package sources, <prgn/apt/ will print warnings related to its
          inability to confirm that packages downloaded from them are
          legitimate and have not been tampered with. For more information
          please see <ref id="pkgmgmt">.
          </p>

<!-- JFS: Bug #376158 -->
          <p>You will notice that, since you are using the new version of
          <prgn/apt/, it will download package differences files (<tt/pdiff/)
          instead of the full package index list. For more information on this
          feature please read <ref id="apt-pdiff">.</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>

<!-- (vorlon) FIXME: I recommend dropping this paragraph, it doesn't seem relevant 
     for sarge->etch?
-->
          <p>Sometimes it's necessary to enable the <tt/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 <var>&lt;package-foo&gt;</var> (from <var>&lt;package-foo-file&gt;</var>) ...
dpkg: error processing <var>&lt;package-foo&gt;</var> (--install):
 trying to overwrite `<var>&lt;some-file-name&gt;</var>',
 which is also in package <var>&lt;package-bar&gt;</var>
dpkg-deb: subprocess paste killed by signal (Broken pipe)
 Errors were encountered while processing:
 <var>&lt;package-foo&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>This section explains how to upgrade your kernel and identifies
          potential issues related to this upgrade. You can either install one of
          the <package/linux-image-*/ packages provided by Debian, or compile a
          customized kernel from source.</p>

<![ %uses-initrd [
          <p>Note that a lot of information in this section is based on the
          assumption that you will be using one of the modular Debian kernels,
          together with <package/initramfs-tools/ and <package/udev/. If you
          choose to use a custom kernel that does not require an initrd or
          if you use a different initrd generator, some of the information may not be
          relevant for you.</p>
]]>
<![ %no-initrd [
          <p>Note that this section contains a lot of information related to
          the use of <package/initramfs-tools/ and <package/udev/. However,
          as the Debian kernels for &architecture; do not use an initrd to
          boot the system, some of this information may not be relevant for
          you. The information is still included as you may have
          <package/udev/ installed for other reasons.</p>
]]>
          <p>Note also that if <package/udev/ is <em/not/ installed on your
          system, it is still possible to use <package/hotplug/ for
          hardware discovery.</p>

<![ %defaulted-2.4 [
        <p>If you are currently using a 2.4 kernel, you should also read
        <ref id="upgrade-to-2.6"> carefully.</p>
]]>

        <sect1 id="kernel-metapackage"><heading>Installing the kernel metapackage</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:
<!-- NOTE (jfs): Users using apt/aptitude might not have their available file
     updated so '^ii' is really unnecessary, maybe dpkg -l 'linux-image*' would be
     better here? -->
          <example>
# dpkg -l "linux-image*" | grep ^ii
          </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/.
<![ %i386 [
          (Note that the 386 flavor no longer exists; if you are currently using
          the 386 kernel flavor, you should install the 486 flavor instead.)
]]>
          You may also use <prgn>apt-cache</prgn> 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 benefits provided by the new kernel version.</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>

        <sect1 id="upgrade-from-2.6"><heading>Upgrading from a 2.6 kernel</heading>

        <p>If you are currently running a 2.6 series kernel from
        &oldreleasename; this upgrade will take place automatically after you do a full upgrade
        of the system packages (as described in <ref id="upgradingpackages">).
        </p>

        <p>If possible, it is to your advantage to upgrade the kernel package
        separately from the main <tt/dist-upgrade/ to reduce the chances of a
        temporarily non-bootable system.  See <ref id="upgrading_kernel"> for a
        description of this process.  Note that this should only be done after the
        minimal upgrade process described in <ref id="minimal_upgrade">.
        </p>

        <p>You can also take this step if you are using your own custom
        kernel and want to use the kernel available in &releasename;.
        If your kernel version is not supported by <package/udev/ then
        it is recommended that you upgrade after the minimal upgrade.
        If your version is supported by <package/udev/ you can safely wait
        until after the full system upgrade.</p>

<!--
         <p><em>TRY</em>: In aptitude, upgrade only 'required' 'important'
         'standard' packages limit by pressing 'l' and input
         !~v(~pextra|~poptional) keep with : for hold this time upgrade by
         pressing 'U' and 'g'  (untested but ...) (You can do this in much
         finer steps.)
-->
        </sect1>

<![ %defaulted-2.4 [
        <sect1 id="upgrade-from-2.4"><heading>Upgrading from a 2.4 kernel</heading>

        <p>If you have a 2.4 kernel installed, and your system relies on 
        <package/hotplug/ for its hardware detection you should first upgrade
        to a 2.6 series kernel from &oldreleasename; before attempting the upgrade. Make
        sure that the 2.6 series kernel boots your system and all your hardware is
        properly detected before you perform the upgrade. The <package/hotplug/ package
        is removed from the system (in favor of <package/udev/) when you do a full system
        upgrade. If you do not do the kernel upgrade before this your system might
        not boot up properly from this point on. Once you have done an upgrade
        to a 2.6 series kernel in &oldreleasename; you can do a kernel upgrade
        as described in <ref id="upgrade-from-2.6">.</p>

        <p>If your system does not rely on <package/hotplug/<footnote>You can
        have the kernel modules needed by your system loaded statically through proper configuration
        of <file>/etc/modules</file></footnote> you can delay the kernel upgrade 
        to after you have done a full system upgrade, as described in <ref
        id="upgrading_other">. Once your system has been upgraded
        you can then do the following (changing the kernel package name to the one most
        suited to your system by substituting <em>&lt;flavor&gt;</em>):
        <example>
# aptitude install linux-image-2.6-&lt;flavor&gt;
        </example>
        </p>

        </sect1>
]]>

        <sect1 id="device-reorder"><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
          <package>udev</package> rules, more specifically, through the definitions at
          <file>/etc/udev/rules.d/z25_persistent-net.rules</file><footnote>
          The rules there are automatically generated by the script
          <file>/etc/udev/rules.d/z45_persistent-net-generator.rules</file> to
          have persistent names for network interfaces. Delete this symlink to
          disable persistent device naming for NICs by <package/udev/.</footnote>.
          Alternatively you can use 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.
          The two alternatives (<package>udev</package> and <prgn>ifrename</prgn>)
          should not be used at the same time.
          </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. Note that this will only work for devices which the kernel
          enumerates in a stable order (like PCI devices).</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 boot time. 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 -u -k all</tt>.</p>

          <p>Once you are running a &releasename; kernel and <package/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>Upon reboot, the system will show up the message "Loading
          initrd...." but it will stop there. Notice that systems with
          outdated firmware will show similar symptoms, although the issue is
          related to kernel incompatibilities (see <ref
          id="upgrade-to-2.6">).</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>
]]>
<![ %uses-initrd [
<!-- #417643 -->
        <sect1 id="boot-timing"><heading>Boot timing issues</heading>

          <p>If an initrd created with <package/initramfs-tools/ is used to
          boot the system, in some cases the creation of device files by
          <package/udev/ can happen too late for the boot scripts to act on.</p>
          <p>The usual symptoms are that the boot will fail because the root
          file system cannot be mounted and you are dropped into a debug shell,
          but that when you check afterwards, all devices that are needed are
          present in <file>/dev</file>. This has been observed in cases where
          the root file system is on a USB disk or on RAID.</p>
          <p>A workaround for this issue is to use the boot parameter
          <tt>rootdelay=<var/9/</tt>. The value for the timeout (in seconds) may
          need to be adjusted.</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>

        <sect1 id="convert-devfs"><heading>Converting from devfs</heading>
          <p>Debian kernels no longer include support for <tt>devfs</tt>,
          so <tt>devfs</tt> users will need to convert their systems
          manually before booting an &releasename; kernel.</p>

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

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

<![ %sparc [
        <sect1 id="missingdrivers"><heading>Possible missing drivers in initrd</heading>
          <p>The &releasename; kernels do not yet have full sysfs support for
          the native sparc sbus. <package/initramfs-tools/ relies on this to
          include drivers for disk controllers in the initrd. If a driver is
          not included in the initrd, your system may fail to boot.
          <p>If your system uses the <tt/esp/ or <tt/qlogicpti/ module to
          access your hard disks, you will need to include that module in
          <file>/etc/initramfs-tools/modules</file> and regenerate the initrd
          before you reboot your system. The initrd can be regenerated using:
          <example>
# update-initramfs -u -k all
          </example></p>
]]>

<![ %hppa [
        <sect1 id="missingdrivers"><heading>Possible missing drivers in initrd</heading>
          <p>The &releasename; kernels do not yet have full sysfs support for
          the native HP bus. <package/initramfs-tools/ relies on this to
          include drivers for disk controllers in the initrd. If a driver is
          not included in the initrd, your system may fail to boot.
          <p>If your system uses the <tt/lasi700/ or <tt/zalon7xx/ module to
          access your hard disks, you will need to include that module in
          <file>/etc/initramfs-tools/modules</file> and regenerate the initrd
          before you reboot your system. The initrd can be regenerated using:
          <example>
# update-initramfs -u -k all
          </example></p>
        </sect1>
]]>

<![ %i386-amd64 [
        <sect1 id="rerunlilo"><heading>Rerun lilo</heading>

          <p>If you are using <package/lilo/ as your bootloader (it is the
          default bootloader for some installations of &oldreleasename;) it is strongly recommended
          that you rerun <prgn>lilo</prgn> after the upgrade:
          <example>
# /sbin/lilo
          </example></p>

          <p>Notice this is needed even if you did not upgrade your system's kernel, as
          <prgn>lilo</prgn>'s second stage will change due to the package upgrade.</p>

          <p>Also, review the contents of your <file>/etc/kernel-img.conf</file> and
          make sure that you have <em>do_bootloader = Yes</em> in it. That way the
          bootloader will always be rerun after a kernel upgrade.
          </p>

          <p>If you encounter any issues when running <prgn/lilo/, review the
          symbolic links in <file>/</file> to <file>vmlinuz</file> and
          <file>initrd</file> and the contents of your
          <file>/etc/lilo.conf</file> for discrepancies.</p>

          <p>If you forgot to rerun <prgn/lilo/ before the reboot or the system
          is accidentally rebooted before you could do this manually, your
          system might fail to boot. Instead of the lilo prompt, you will only
          see <em/LI/ when booting the system<footnote>For more information on
          <prgn/lilo/'s boot error codes please see <url
          id="http://tldp.org/HOWTO/Bootdisk-HOWTO/a1483.html" name="The Linux
          Bootdisk HOWTO">.</footnote>. In order to
          recover from this you will have to start up a media installation disk
          in <em/rescue/ mode. For
          more information on how to do this please review the Debian Installer's
          Manual chapter <url
          id="http://www.debian.org/releases/etch/i386/ch08s07.html"
          name="Recovering a Broken System"> and the 
          <url
          id="http://wiki.debian.org/DebianInstaller/FAQ" name="Debian Installer
          FAQ">.</p>

        </sect1>
]]>

<![ %s390 [
        <sect1 id="s390-config"><heading>S/390 hardware configuration</heading>

          <p>Not all S/390 hardware can be configured automatically. For the
          &releasename; kernels a new utility <package/sysconfig-hardware/ is
          used to correctly set up devices. Unfortunately documentation for
          this utility and its configuration files is not yet available. The
          configuration files for <package/sysconfig-hardware/ can be found
          under <file>/etc/sysconfig/</file>.</p>

          <p>Especially if your system is currently running a 2.4 kernel,
          getting the configuration right can be a challenge. If you need any
          help, feel free to contact the
          <url id="http://lists.debian.org/debian-s390"
          name="Debian S/390 mailing list">.</p>

          <p>First install the utility and regenerate the initramfs initrd as
          the utility provides some scripts that need to be included in the
          initrd:
          <example>
# aptitude install sysconfig-hardware
# update-initramfs -u -k all
          </example></p>

        <sect2 id="s390-dasd"><heading>Configuration for disks</heading>

          <p>This is done by modifying <file>/etc/zipl.conf</file>. The
          sysconfig utility can use the device path to the root device to
          enable it, which means that this path needs to be passed in the kernel
          boot parameters. For a regular dasd, the path is composed as follows:
          <example>
&lt;bus&gt;-&lt;device&gt;
          </example>

          For the <tt/root/ parameter the partition needs to be appended to
          the path. So if your dasda is <tt/0.0.0122/, instead of
          <file>root=/dev/dasda1</file> you would include the following in
          the <tt/parameters/ line in <tt>/etc/zipl.conf</tt>:
          <example>
root=/dev/disks/by-path/ccw-0.0.0122-part1
          </example>

          Or, alternatively you can use the <tt/enable/ parameter to specify
          the device to be enabled; in that case the partition:
          <example>
root=/dev/dasda1 enable=ccw-0.0.0122
          </example>

          The paths to be used can vary for different devices. For example, for
          disks on a zFCP fiberchannel host adapter, the path consists of bus,
          device, driver, wwpn and lun. The parameters for a RAID1 would look
          like (on a single line):
          <example>
root=/dev/md0 enable=ccw-0.0.2900-zfcp-0x21000020371c93a5:0
enable=ccw-0.0.2900-zfcp-0x21000020371d8f94:0
          </example></p>

          <p>Other dasd devices (dasds not needed to bring up the root file
          system) are enabled through configuration files in
          <file>/etc/sysconfig/hardware/</file>. For a regular dasd, you just
          need to touch a file with the device path in its name:
          <example>
# cd /etc/sysconfig/hardware
# touch config-ccw-0.0.0122
          </example>

          For disks on a zFCP fiberchannel host adapter the individual devices
          are listed inside the file. Using the same example as above,
          create a file <file/config-ccw-0.0.2900/ containing (second device
          truncated for readability):
          <example>
ZFCP_DEVICES=(0x21000020371c93a5:0x0000000000000000 0x2100...:0x...)
          </example></p>

        </sect2>
        <sect2 id="s390-other"><heading>Configuration for network devices</heading>

          <p>Network devices are enabled through configuration files in
          <file>/etc/sysconfig/hardware/</file>. For a ctc network device with
          read channel <tt/0.0.0a00/ and write channel <tt/0.0.0a01/ and using
          the S/390 protocol, you would create a file <file/config-ccw-0.0.0a00/
          containing:
          <example>
CCWGROUP_CHANS=(0.0.0a00 0.0.0a01)
CTC_PROTOCOL=0
          </example>

          For a qeth network device with layer2 mode enabled, this could be a
          file <file/config-ccw-0.0.0600/:
          <example>
CCWGROUP_CHANS=(0.0.0600 0.0.0601 0.0.0602)
QETH_OPTIONS=(layer2)
          </example></p>

          <p>Supported options for ctc are: <tt/CTC_PROTOCOL/ and <tt/CTC_BUFFER/;
          and for qeth: <tt/QETH_PORTNAME/, <tt/QETH_PORTNO/ and <tt/QETH_OPTIONS/.
          </p>
          <p>As network devices on S/390 do not have a stable MAC address, it is
          not possible to use <package/udev/ persistent device naming. Instead you
          can add an option <tt/INTERFACE_NAME/ in the configuration file to
          rename an interface.</p>

        </sect2>
        </sect1>
]]>

        <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="for_next"><heading>Preparing for the next release</heading>

          <p>After the upgrade there are several things you can do 
          to prepare for the next release.</p>

          <p><list>

          <item><p>If using <prgn/grub/, edit <file>/etc/kernel-img.conf</file>
          and adjust the location of the <prgn/update-grub/ program changing
          <file>/sbin/update-grub</file> to <file>/usr/sbin/update-grub</file>.</p>

          <item><p>If the new kernel image metapackage was pulled in as a
          dependency of the old one, it will be marked as automatically installed,
          which should be corrected:
<example>
# aptitude unmarkauto $(dpkg-query -W 'linux-image-2.6-*' | cut -f1)
</example>
</p>
        <item><p>Remove &oldreleasename;'s kernel metapackages by running:
<example>
# aptitude purge kernel-image-2.6-&lt;flavor&gt;
</example>
</p> 

        <item><p>Move any kernel configuration values at
        <file>/etc/network/options</file> to <file>/etc/sysctl.conf</file>.</p>

        <item><p>Remove obsolete and unused packages as described in <ref
        id="obsolete">.  You should review which configuration files they use
        and consider purging the packages to remove their configuration files</p>

        </list></p>

        </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 latter case,
         packages might still be present in the "unstable" distribution.</p>

<!-- (vorlon) FIXME: not true in etch because 'Obsolete and Locally Created 
     Packages' is not the default view AFAICS?
-->
         <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>

<!-- (vorlon) FIXME: AIUI, cruft is not useful for this? -->
         <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-effects 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="udev"> <heading>Problems with devices related to udev</heading>
          <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>

<![ %defaulted-2.4 [
          <sect1 id="incompatible-2.4">
          <heading>Some applications may no longer work with a 2.4 kernel</heading>
          <p>Some applications in &releasename; may no longer work with a 2.4
          kernel, for example because they require <tt/epoll()/ support, which
          is not available in 2.4 kernels. Such applications may either not
          work at all or not work correctly until the system has been rebooted
          with a 2.6 kernel.</p>
          <p>One example is the HTTP proxy <package/squid/.</p>
          </sect1>
]]>

          <sect1 id="window-scaling"><heading>Certain network sites cannot be reached by TCP</heading>
          <p>
          Since 2.6.17, Linux aggressively uses TCP window scaling which is specified in RFC 1323.
          Some servers have a broken behavior, 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>

<![ %i386 [
          <sect1 id="poweroff"><heading>Automatic poweroff stops working</heading>
          <p>
          On some older systems, <tt>shutdown -h</tt> 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>
]]>

<!-- JFS: Bug #376158 -->
          <sect1 id="apt-pdiff"><heading>Slower updates of APT package index files</heading>
          <p>By default, the &releasename; version of <prgn>apt</prgn> uses a
          new way to update APT package
          index files (when you run <tt/aptitude update/) which downloads differences
          files (instead of the full package index file) called <tt/pdiff/. This new
          feature should use less bandwidth and be faster for most systems.
          Unfortunately, it can also have the opposite effect of making the updates
          slower on systems with fast network connections (or a very nearby
          mirror) which are infrequently updated, as it might take more time
          for the system to merge the differences files than to download a
          full package index.  It is possible to disable this feature by adding
          <tt>Acquire::Pdiffs "false";</tt> to the
          <file>/etc/apt/apt.conf</file> configuration file.</p>
<!-- For more info, see thread "These new diffs are great, but...", d-devel, july 2006 -->

          <p>This change mostly affects users of the <em/unstable/ and
          <em/testing/ branch of &debian;, due to the changing nature of these
          archives. Users of &releasename; will notice this
          feature mainly when updating their package status for the security
          archive.</p>
          </sect1>

<![ %i386 [
          <sect1 id="hp-acpi"><heading>ACPI support disabled for some HP laptop models in &releasename; kernel</heading>
          <p>
          Certain models of HP laptops have an ACPI BIOS that is incompatible with the
          Linux 2.6.18 kernel shipped in &releasename;, which would prevent the fans from
          spinning up leading to unnecessary heat stress. Also, fans might not work after
          the system is suspended. The kernel therefore disables ACPI support
          internally when it detects certain ACPI BIOS versions.  Models known
          to be affected by this change include the HP nx6125, nx6120, nx6325,
          nc6120 and nc6000 models.
          </p>
          <p>
          Users who require ACPI support on these systems may install a Linux 2.6.19 or
          later kernel.  Please see Debian bug
          <url id="http://bugs.debian.org/404143" name="#404143"> and
          <url id="http://bugs.debian.org/400488" name="#400488">,
          and Linux Kernel's bugs
          <url id="http://bugzilla.kernel.org/show_bug.cgi?id=5534" name="#5534">
          and 
          <url id="http://bugzilla.kernel.org/show_bug.cgi?id=7122" name="#7122">
          for additional information.
          </p>
          </sect1>
]]>

          <sect1 id="asynchronous-network-start"><heading>Asynchronous network initialization may cause unpredictable behavior</heading>
          <p>On systems which use <package/udev/ to load drivers for network
          interfaces, it is possible due to the asynchronous nature of
          <package/udev/ that the network driver will not be loaded before
          <prgn>/etc/init.d/networking</prgn> runs on system boot.  Although
          including <tt/allow-hotplug/ to <file>/etc/network/interfaces</file> (in
          addition to <tt/auto/) will ensure that the network interface is enabled 
          once it becomes available, there is no guarantee that this will finish
          before the boot sequence begins to start network services, some of which
          may not behave correctly in the absence of the network interface.</p>

          </sect1>

<![ %not-s390 [
          <sect1 id="wpa"><heading>Trouble when using WPA secured wireless networks</heading>
          <p>In &oldreleasename;, the <package/wpasupplicant/ package was
          set up as a system service, configured via
          <file>/etc/default/wpasupplicant</file> and a user-provided
          <file>/etc/wpasupplicant.conf</file>.</p>

          <p>In &releasename;, <file>/etc/init.d/wpasupplicant</file> has been
          dropped and the Debian package now integrates with
          <file>/etc/network/interfaces</file>, similar to other packages such as
          <package/wireless-tools/.  This means <package/wpasupplicant/ no longer
          provides a system service directly.</p>

          <p>For information on configuring wpasupplicant please refer to
          <file>/usr/share/doc/wpasupplicant/README.modes.gz</file>, which gives 
          examples for <file>/etc/network/interfaces</file> files.  Updated
          information about the usage of the <package/wpasupplicant/ package
          in Debian can be found in the <url id="http://wiki.debian.org/WPA"
          name="Debian Wiki">.</p>
          </sect1>
]]>

          <sect1 id="partitionenc"><heading>Problems with non-ASCII characters in filenames</heading>
          <p>
          Mounting vfat, ntfs or iso9660 filesystems with files that include
          non-ASCII characters in their filenames will give failures when one 
          tries to use the filenames unless mounting is done with the utf8 
          option. An indication might be the following failure: 'Invalid or 
          incomplete multibyte or wide character'. A possible solution is to
          use <tt>defaults,utf8</tt> as mount options for vfat, ntfs and iso9660 
          filesystems when they contain filenames with non-ASCII characters.
          </p>
          <p>Note that the Linux kernel does not support case-insensitive 
          filename handling for vfat when the <tt>utf8</tt> option is used.</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 behavior 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>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>

<!-- JFS: Can't this device name change even for some other disk controllers? I've found
     references in debian-user posts talking about some strange chipsets and BIOS
     which are seen in sarge' 2.4 as hda and in etch's 2.6 as hdf... -->
<![ %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<footnote>It will boot the kernel but will fail when trying
          to mount the root file system and will abort with an error <em>waiting for root file system</em>
          followed by <em>unable to mount /dev/hdX ..not found</em>.
          You can use the <prgn/initramfs/ shell to fix this issue, after you
          identify the newly assigned device names in the kernel boot messages or by reviewing
          the contents of <file>/dev/disk/</file>.</footnote>.</p>
]]>

<!-- Bug: #416720 -->
<![ %ia64 [
         <p>HP Itanium systems running older firmware are incompatible with the
            2.6 kernel in &releasename;. That means you should upgrade your
            system to the latest firmware before upgrading your kernel. It is
            recommended you do this before the system upgrade, as if you are 
            already running a 2.6 kernel you will automatically retrieve the
            latest kernel when upgrading the rest of the system (see <ref
            id="upgrading_other">). Failing to do this will result in an system
            that does not boot.
         </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 CD-ROM to hand, in case misconfiguration of the bootloader
          prevents you from 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-xorg</tt> or by
          editing <file>/etc/X11/xorg.conf</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>

<!-- FIXME: should be udev now? (vorlon) -->
        <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 -->
      </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.
        However, experience has shown that 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 the 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 the distribution upgrade from 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>

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

      </sect>

<!-- JFS: Bug #406300 -->
      <sect id="xorg-8bit"><heading>No support for 8-bit displays in many applications</heading>

      <p>After the upgrade to the Xorg and the latest libraries, X terminals
      which can only represent colors 8 bits depth will not work. This is
      because the Cairo 2D vector graphics library (<package/libcairo2/)
      doesn't have 8-bit pseudocolor support. This library is used by the GNOME
      and Xfce desktops as well as by many desktop applications compiled
      with the Gtk2+ toolkit, such as <package/abiword/.</p>

<!-- TODO: make this arch-specific ? This applies to remote terminals, so
     it might not make sense to make it arch-specific ... -->
<!-- Specific models mentioned in freedeskop's BTS, might not be complete:
     - Tektronix XP117C X terminal,
     - NCD: 19r X11, 256 color X terminal
     - IBM: Netstation
     - SUN: Ultra 10, Ultra 5, Ultra 60 (Solaris 8 with Xsun)
     - SGI: Octane
-->
      <p>Known systems that are affected by this include some Sun machines and
      X terminals from Tektronix, NCD, IBM and SGI, as well as some other
      remote X windowing systems. You should configure these terminals to use
      16-bit colour, if possible.</p>

      <p>More information is available 
      in Freedesktop's <url id="https://bugs.freedesktop.org/show_bug.cgi?id=4945"
      name="bug #4945">.</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) <package/exim/, which has been replaced
      by the completely new package <package/exim4/.</p>

      <p><prgn/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
      <prgn/exim/ 3.xx, please upgrade your <package/exim/ installation to <package/exim4/ manually.
      Since <package/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 <package/exim/ package is not going to be upgraded and that it won't get
      security support after support for &oldreleasename; has been discontinued.</p>

      <p>Note that, depending on your configuration of <package/debconf/, you may not
      be asked any configuration question during installation of <package/exim4/.
      If no questions are asked, the system will default to a 'local delivery' setup.
      Configuration is possible using the command <tt/dpkg-reconfigure exim4-config/.</p>

      <p>The <package/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/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 <prgn/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>

        <p>If you are using the experimental ITK MPM (from the
        <package/apache2-mpm-itk/ package), the cgi module will not be correctly
        enabled by default. To properly enable it, you will need to manually
        disable <tt/mod_cgid/ and enable <tt/mod_cgi/:
        <example>
# cd /etc/apache2/mods-enabled
# rm cgid.conf cgid.load
# ln -s ../mods-available/cgi.load .
# /etc/init.d/apache2 force-reload
        </example></p>

      </sect>

      <sect id="zope"> <heading>Upgrading Zope and Plone</heading>
        <p>Zope and all related products have been updated. Many products were
        also dropped from the distribution (either because they were obsoleted,
        or because they are incompatible with the newer Zope, CMF or Plone).</p>
        <p>Unfortunately there is no easy and guaranteed way to upgrade a
        complex <prgn/zope/ or <prgn/plone/ server. Even though Plone includes
        a migration tool, experience has shown that automatic migrations
        can easily fail.</p>

        <p>For this reason, users are recommended to set up their system so they
        can continue to run the &oldreleasename; installation of Zope/Plone
        alongside the new &releasename; versions while testing the migration.</p>
        <p>The easiest and safest way to achieve this, is to make a copy of your
        &oldreleasename; system to another hard disk or partition, and then
        upgrade only one of the two copies. You can then use <prgn/chroot/ to
        run the &oldreleasename; version in parallel to the &releasename;
        version.</p>

        <p>It is not possible to have the old and new versions of Zope/Plone
        installed together on an &releasename; system, partly because the old
        packages depend on <package/python2.3/ which cannot be installed
        together with <package/python2.4/.</p>
      </sect>

      <sect id="tar"> <heading>Wildcard expansion (globbing) with GNU tar</heading>
        <p>Previous versions of GNU <prgn/tar/ assumed shell-style globbing
        when extracting files from or listing an archive. For example:
        <example>
tar xf foo.tar '*.c'
        </example>
        would extract all files whose names end in '.c'.  This behavior was not
        documented and was incompatible with traditional <prgn/tar/
        implementations. Therefore, starting from version 1.15.91, GNU
        <prgn/tar/ no longer uses globbing by default.  For example, the above
        invocation is now interpreted as a request to extract from the archive
        the file named '*.c'.</p>
        <p>See <file>/usr/share/doc/tar/NEWS.gz</file> for further information.</p>
      </sect>

      <sect id="nis"><heading>NIS and Network Manager</heading>
        <p>The version of <prgn/ypbind/ included with <package/nis/ for
        &releasename; contains support for Network Manager. This support causes
        <prgn/ypbind/ to disable NIS client functionality when Network Manager
        reports that the computer is disconnected from the network. Since Network
        Manager will usually report that the computer is disconnected when it is
        not in use, NIS users with NIS client systems should ensure that Network
        Manager support is disabled on those systems.</p>
        <p>This can be done by either uninstalling the <package/network-manager/
        package, or editing <file>/etc/default/nis</file> to add <tt/-no-dbus/ to
        <tt/YPBINDARGS/.</p>
        <p>The use of <tt/-no-dbus/ is the default for new installs of Debian, but
        was not the default in previous releases.</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>).</p>
      </sect>

<!-- JFS: Bug #400311 -->
      <sect id="mozilla-security"> <heading>Security status of Mozilla products</heading>
        <p>The Mozilla programs <package>firefox</package> and <package>thunderbird</package>
        (rebranded in Debian to <package>iceweasel</package> and <package>icedove</package>, respectively),
        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 of not shipping
        large functional changes in security updates.
        We cannot predict it today, but during the 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>

<!-- JFS: Bug #400838 -->
      <sect id="kde-desktop-changes"> <heading>KDE desktop</heading>
        <p>KDE media handling has changed in the version available in
        &releasename; from using <file>device:/</file> to <file>media:/</file>.
        Some user configuration files might have stored <file>device:/</file>
        links in them which should be adapted. Notably,
        <file>~/.kde/share/apps/konqsidebartng/virtual_folders/services</file>
        contains this reference and can be safely deleted as it will not be
        created when setting up new users.

        <p>There have been many changes in the KDE desktop environment from
        the version shipped in &oldreleasename; to the version in
        &releasename;, you can find more information in the <url
        id="http://www.kde.org/announcements/announce-3.5.php" name="KDE
        3.5 Release Notes">.</p>
      </sect>

<!-- JFS: Bug #387921 -->
      <sect id="gnome-desktop-changes"> <heading>GNOME desktop changes and support</heading>
        <p>If you used the GNOME desktop in &oldreleasename; you will not benefit
        from some of the changes introduced in the default configuration in
        Debian for &releasename;. In some extreme cases the GNOME desktop might
        not properly handle your old configuration and might not behave properly.</p>

        <p>If you have not heavily invested in configuring your GNOME desktop
        you might want to move the the <file>.gconf</file> directory in user's
        home directories to a different name (such as <file>.gconf.old</file>)
        so that it gets recreated, with the default configuration for
        &releasename;, upon starting a new session.</p>

        <p>With the release of &releasename;, Debian no longer contains packages for
        most of the obsolete version 1 release of GNOME, although some packages
        remain in order to support some Debian packages which have not yet
        been updated to GNOME 2. Packages for GTK1.2 remain fully maintained.</p>

        <p>There have been many changes in the GNOME desktop environment from
        the version shipped in &oldreleasename; to the version in
        &releasename;, you can find more information in the <url
        id="http://www.gnome.org/start/2.14/notes/en/" name="GNOME
        2.14 Release Notes">.</p>
      </sect>

<!-- FJP: Bug #398887 -->
      <sect id="default-editor"> <heading>Default editor</heading>
        <p>If you were using <prgn/vim/ as your default editor, this may
        be changed to <prgn/nano/ during the upgrade.</p>

        <p>Administrators who wish to change the default editor for all users
        will have to update the alternatives system using:

          <example>
# update-alternatives --config editor
          </example>
        </p>

        <p>Users wishing to change the default editor can define the
        environment variable <em>EDITOR</em> by introducing the following lines
        in their own profiles:

          <example>
EDITOR=vi
export EDITOR
alias editor=$EDITOR
          </example>
        </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 favorite 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 future 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 additional information be
        needed.</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 also 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>

          <p>If you upgrade your system using a Debian mirror, it will
          automatically be upgraded to the latest &oldreleasename; point
          release.</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 an &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:
-->