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.185 2007-03-27 23:28:16 jfs Exp $">
]>

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

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

        <p>The 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 users 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>On front page's 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>Session logs using <package>script</package>, as described in
            <ref id="record_session">.</p></item>

            <item><p>The status of your package database before and after the
            upgrade, using the backup procedure described at <ref
            id="backup">.

            <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 uses <package>debiandocsgml</package>. Its sources
          are available in the <em>Debian Documentation Project</em>'s CVS.
          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. Upgrading from this unofficial
        version should be possible using these Release Notes, but is not
        supported.</p>

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

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

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

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

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

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


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

<!-- TODO (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 6,200 new packages, for a total of over 18,000 packages. Most
           of the software in the distribution has been updated: over 10,500
           software packages (this is 67% of all packages in &oldreleasename;).
           Also, a significant number of packages (over 3400, 22% 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. Amongst
           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 to other desktop applications include the upgrade of
           Evolution 2.6.3 and Gaim 2.0.  The Mozilla suite has also been updated
           but the main programs have been renamed: <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>This release also includes, amongst others, 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.5, 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><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>The official &debian; distribution now ships on thirteen to fifteen
           binary CDs (depending on the architecture) and a similar number of
           source CDs. A DVD version of the distribution is also available.</p>

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

        <sect1 id="secureapt"><heading>Secure APT</heading>

<!-- FIXME: More content needed here? -->
           <p><prgn/apt-secure/ (also known as <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>.</p>

           <p>In its default configuration, <prgn>apt-secure</prgn> will
           warn if packages are downloaded from sources that are not authenticated.
           Future releases might force all packages to be verified before downloading
           them. Unofficial apt sources administrators 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 <prgn>apt-secure</prgn>'s manual
           page, 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="wiki documentation">.</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 no longer has a <tt/.debian.net/ address,
           but now uses a <tt/.debian.org/ address. Please make sure to update
           your <file>/etc/apt/sources.list</file> accordingly if you were
           already using this service.</p>

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

        </sect1>
        </sect>

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

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

           <p>In these Release Notes we'll only list the major changes in the
           installer. If you are interested in an overview of the detailed
           changes since &oldreleasename;, please check the release announcements
           for the &releasename; beta and RC releases 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>The installation used to be split into two parts:
             setting up the base system and making it bootable, followed
             by a reboot and after that the execution of <prgn/base-config/
             which would take care of things like user setup, setup of the
             package management system and installation of additional
             packages (using tasksel).</p>
             <p>For &releasename; the second stage has been integrated into
             Debian Installer itself. This has a number of advantages,
             including increased security and the fact that after the reboot
             at the end of the installation the new system should already have
             the correct timezone and, if you installed the Desktop environment,
             will at once start the graphical user interface.</p></item>

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

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

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

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

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

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

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

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

             <tag>Simplified mail configuration</tag>
             <item><p>The installation system setups a basic configuration for
             the system's mail server which will only provide for local e-mail
             delivery, if the "standard system" is installed. 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.
             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. ISO images for
             alternate desktop environments will also be available.</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.
             Languages dropped in this relase due to lack of translation
             updates include Persian and Welsh. 
<![ %g-i [
             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.
]]>
             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
             have 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
      necessar for that language (dictionaries, documentation, fonts...) both
      in standard and desktop enviroments. Configuration that is no longer
      handled automatically include the papersize configuration and some
      advanced keyboard settings on Xorg for some languages.</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>

      </chapt>

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

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

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

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

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

        <p>You may also want to check the <url id="&url-installer;index#errata"
        name="errata"> for debian-installer for a list of knonw issues.</p>

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

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

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

      </sect>
]]>

      <sect id="improves_in_etch"><heading>System improvements</heading>

       <p>Users installing &releasename; will benefit from some improvements
       in the &debian; operating system. Most of these improvements
       will be carried over to upgrades from &oldreleasename; but there
       are some changes that will only affect new installs:
       </p>

       <p><list>

<!-- Bug 301138, fixed in etch -->
       <item>Development packages are now of <em>Optional</em> priority.
       This includes the standard C/C++-compiler, <package>gcc</package>, as well 
       as some other software (<package>dpkg-dev</package>,
       <package>flex</package>, or <package>make</package>) and development
       headers (<package>libc6-dev</package>,
       <package>linux-kernel-headers</package>). 
<!-- TODO: Point to the bug report for the full list of packages in case
     users want to remove them ? -->
       This reduces the disk space needed for a standard installation.
       </item>

<!-- TODO: Recommend users to remove unused desktop environments ? -->
       <item>There are three different tasks for Desktop environments users can
       choose from: GNOME, KDE or Xfce. An installation of the Desktop task in
       &oldreleasename; would install both GNOME or KDE.</item>

       <item>The default inet superdaemon is <package>openbsd-inetd</package>
       instead of <package>netkit-inetd</package>. It will not be started if no
       services are configured, which is the default.</item>

       <item>The variant installed for <prgn/vi/ by default is a compact version of
       <prgn/vim/ (<package/vim-tiny/) instead of <package/nvi/.

       <item>The &releasename; installer sets up ext2 and ext3 filesystems so
       that they have "directory indexes", a feature which speeds operations on
       directories with many files. It does this by turning on the
       <em/dir_index/ and <em/filetype/ flags when the filesystem is created.
       Users upgrading from &oldreleasename; need to set this flags manually
       with <prgn/tune2fs/.</item>

<!-- TODO: Add for lenny, link to utf8-migration-tool, which is right now not
     available for etch -->
       <item>The &debian; installer will setup all localized environments using
       UTF-8 as the default encoding instead of language-specific encoding.
       Users upgrading to &releasename; will have to switch to this encoding
       by configuring their environment and locale definitions.</item>

       </list></p>

<!-- TODO: make it conditional based on arquitecture ? -->
      <p>Additional packages are pulled in based on the system being installed on or on the user
      configuration. Users running the installer in a laptop system will
      automatically get a set of packages specific for laptops, and so will
      users configuring a localized environment. Even though these packages are
      not pulled in when upgrading from &oldreleasename; to &releasename; they
      are still available for users through <em>tasks</em>. Users wishing to
      install these tasks just need to run <prgn/aptitude/ interactively and select the
      appropiate tasks from the <em>Tasks</em> item presented in the user interface.</p>

      <p>For more information please see the <url id="http://wiki.debian.org/Sarge2EtchUpgrade"
      name="wiki pages"> that describe the upgrade from &oldreleasename; to &releasename;.</p>

      <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;
        you will thereby help improve Debian.</p>

      </sect>

      </chapt>


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

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

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

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

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

          <p>Before upgrading your system, it is strongly recommended that
          you make a full backup, or at least backup any data or
          configuration information you can't afford to lose. The upgrade
          tools and process are quite reliable, but a hardware failure in
          the middle of an upgrade could result in a severely damaged
          system.</p>

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

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

          <p>It's wise to inform all users in advance of any upgrades you're
          planning, although users accessing your system via an <prgn/ssh/
          connection should notice little during the upgrade, and should be
          able to continue working. 
          In order to gain extra safety margin, we suggest you to run
          upgrade processes in the virtual console provided by the
          <prgn/screen/ program which enables the safe reconnection and ensures
          the uninterrupted upgrade processes even if the remote connection
          process fails by chance.</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 
          <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>

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

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

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

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

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

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

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

       <p>Both <prgn/aptitude/ and <prgn/apt/ will show you detailed information
       of the disk space needed for the installation. 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>.

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

       <item>Remove old packages you no longer use. If you have
       <prgn/popularity-contest/ installed, you can use
       <prgn/popcon-largest-unused/ to list the packages you do not use in the
       system that occupy the most space. You can also use <prgn/deborphan/
       or <prgn/debfoster/ to find obsolete packages (see 
       <ref id="obsolete">).
       
       <item>Remove packages 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>).
       
       <item>Temporarily move to another system, or permanently remove, system
       logs residing under <file>/var/log/</file>.

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

        <sect1 id="glibc-kernel"><heading>Support for 2.2-kernels has been dropped</heading>
          <p>In case you run a kernel prior to 2.4.1,
          you need to upgrade to (at least) the
          2.4-series before upgrading <package/glibc/.
          This should preferable be done before starting the upgrade.
          It is recommended you directly upgrade to the 2.6-kernel (available
          in &oldreleasename;, instead of upgrading to a 2.4-kernel series.
          </p>
        </sect1>

        </sect>

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

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

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

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

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

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

          <p>Regardless of the method used for upgrading, it is recommended
          that you check the status of all packages first, and verify that
          all packages are in an upgradable state. The following command
          will show any packages which have a status of Half-Installed or
          Failed-Config, and those with any error status.

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

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

          or

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

          <p>It is desirable to remove any holds before upgrading. If any
          package that is essential for the upgrade is on hold, the upgrade
          will fail.</p>

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

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

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

          <p>If you changed and recompiled a package locally, and didn't rename
          it or put an epoch in the version, you must put it on hold to prevent
          it from being upgraded.</p>

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

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

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

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

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

        </sect1>
        </sect>

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

           <p>Any package needed for installation that is fetched from the
           network is stored in <file>/var/cache/apt/archives</file>
           (and the <file>partial/</file> subdirectory, during download), so
           you must make sure you have enough space before attempting to
           start the installation. With a reasonably extended Debian
           installation, you can expect at least 300 MB of downloaded
           data.</p>

         </sect1>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

          <example>
# mount /cdrom    # this will mount the CD to the mount point
# ls -alF /cdrom  # this should show the CD's root directory
# umount /cdrom   # this will unmount the CD
          </example></p>

          <p>Next, run:

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

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

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

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

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

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

          <p>Next you should double check that the APT source entries (in
          <file>/etc/apt/sources.list</file>) refer either to
          "<tt/&releasename;/" or to "<tt>stable</tt>". 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 -a ~/upgrade-&releasename;.script 2>~/upgrade-&releasename;.time
          </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 id="minimal_upgrade"><heading>Minimal system upgrade</heading>

        <p>TODO</p>

        <p>Run 
          <example>
# aptitude upgrade
          </example></p>

        <p>Followed by:</p>

        <p>Server system with no X, do a minimal upgrade with:

          <example>
# aptitude install initrd-tools
          </example></p>

        <p>Server system with some X, (xfree86-common) do a minimal upgrade with:

          <example>
# aptitude install initrd-tools x11-common
          </example></p>

        <p>Desktop system, use this instead:

          <example>
# aptitude install initrd-tools libfam0 xlibmesa-glu
          </example></p>

        <p>Note: After this minimal upgrade has finished you might want to
        consider upgrading the kernel before upgrading the full system,
        as described in <ref id="newkernel">.
        Doing so reduces the timeframe in which, if the system will not
        properly boot if rebooted accidentally.
        This is because the full upgrade will
        install a new version of <prgn/udev/ and will remove <prgn/hotplug/.
        If you are running a desktop environment large parts of the
        system will be removed if you do the kernel upgrade here.</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>

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

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

          <p>Sometimes it's necessary to enable APT::Force-LoopBreak option
          in APT to be able to temporarily remove an essential package due
          to a Conflicts/Pre-Depends loop. <prgn/aptitude/ will alert you of
          this and abort the upgrade. You can work around that by specifying
          <tt>-o APT::Force-LoopBreak=1</tt> option on <prgn/aptitude/
          command line.</p>
<!-- JFS: Shouldn't this mention also Apt's configuration file? -->

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

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

          to eliminate some of the offending packages, or

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

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

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

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

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

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

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

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

          <p>During the upgrade, you will be asked questions regarding the
          configuration or re-configuration of several packages. When you are
          asked if any file in the <file>/etc/init.d</file> or
          <file>/etc/terminfo</file> directories, or the
          <file>/etc/manpath.config</file> file should be replaced by the
          package maintainer's version, it's usually necessary to answer `yes'
          to ensure system consistency. You can always revert to the old
          versions, since they will be saved with a <tt/.dpkg-old/
          extension.</p>

          <p>If you're not sure what to do, write down the name of the
          package or file, and sort things out at a later time. You can
          search in the typescript file to review the information that
          was on the screen during the upgrade.</p>

        </sect1>
        </sect>

        <sect id="newkernel"><heading>Upgrading your kernel and related
        packages</heading>

          <p>You should upgrade the Linux kernel separately from the rest of
          your packages.
<!-- TODO: add something in "before you upgrade", and get the order right -->
          You may wish to do so yourself, either by installing one
          of the <package/linux-image-*/ packages or by compiling a customized
          kernel from sources.
          Please read the information in this section about potential issues
          with kernel upgrades.</p> 

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

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

        <sect1><heading>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 unnecesary, maybe dpkg -l 'linux-image*' would be
     better here? -->
          <example>
# dpkg -l | grep '^ii  linux-image'
          </example></p>

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

          <p>If you are unsure about which package to select, run
          <tt>uname -r</tt> and look for a package with a similar name.
          For example, if you see '2.4.27-3-686', it is recommended that you
          install <package/linux-image-2.6-686/.
          You may also use <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>

<!-- JFS: Bug #413458, undeclared linux depency on coreutils' readlink's -m option -->
        <p>If you are currently running a 2.6 series kernel from
        &oldreleasename; this upgrade will take place after do a full upgrade
        of the system packages (as described in <ref id="upgradingpackages">).
        </p>

        <p>Take in account that the <prgn/udev/ version in &releasename; does
        not support kernel earlier than 2.6.15 (which includes
        &oldreleasename; 2.6.8 kernels), conversely the <prgn/udev/ version in
        &oldreleasename; will not work properly with the latest kernels.
        As a consequence, the previous kernel package will probably not boot
        properly after this upgrade. Similarly, there is a time window through
        the upgrade in which <prgn/udev/ has been upgraded but not the
        latest kernel. If the system were to be rebooted at this point,
        in the middle of the upgrade, it might not be bootable.</p>

<!-- JFS: Bug #325568 -->
        <p>Consequently, you might want to upgrade to the latest kernel
        before doing the full upgrade. Before you can upgrade to the 2.6
        series kernel available in &releasename; you will have to
        upgrade to the latest version of <package/coreutils/ and
        <package/initrd-tools/. To upgrade the kernel before the upgrade, take 
        all the steps up to and including the steps related to the a minimal
        upgrade of the system, as described in <ref id="minimal_upgrade">,
        and then do the following:
        <example>
# aptitude install initrd-tools coreutils linux-image-2.6-686
        </example>
        </p>

        <p>This step will also update libc6, install <prgn/udev/ and
        remove <package/base-config/ and <package/hotplug/.</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 <prgn/udev/ then
        it is recommended you upgrade after the minimal upgrade.
        If your version is supported by <prgn/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>

        <sect1 id="upgrade-from-2.4"><heading>Upgrading from a 2.4 kernel</heading>
        <p>TODO</p>

        </sect1>

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

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

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

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

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

<![ %i386 [
        <sect1><heading>386 kernel flavour deprecated</heading>
          <p>Support for the 80386 sub-archicture for &arch-title; has been dropped
          in &releasename;.  The 386 kernel flavor is no longer supported and has been
          replaced by the new 486 flavour.</p>
        </sect1>
]]>
          
        <sect1 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 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. You can also avoid this by
          using <prgn>udev</prgn> rules, more specifically, through the
          definitions at
          <file>/etc/udev/rules.d/z25_persistent-net.rules</file><footnote>
          The rules there are automatically generated to have persistent names for network
          interfaces</footnote>. Both alternatives (<prgn>ifrename</prgn>
          and <prgn>udev</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.</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 -k all</tt>.</p>

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

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

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

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

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

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

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

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

        </sect1>
]]>

        </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="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 lilo after the upgrade:
          <example>
# /sbin/lilo
          </example></p>

          <p>Notice this is needed even if you did not upgrade your system's kernel, as
          lilo'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>, as well as 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 <url
          id="http://wiki.debian.org/DebianInstaller/FAQ" name="DebianInstaller
          FAQ">.</p>

        </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="obsolete"><heading>Obsolete packages</heading>

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

         <p>Introducing several thousand new packages, &releasename; also
         retires and omits more than two thousand old packages that were in
         &oldreleasename;. It provides no upgrade path for these obsolete
         packages. While nothing prevents you from continuing to use an
         obsolete package where desired, the Debian project will usually
         discontinue security support for it a year after &releasename;'s
         release<footnote>Or for as long as there is not another release in
         that time frame. Typically only two stable releases are supported
         at any given time.</footnote>, and will not normally provide other
         support in the meantime. Replacing them with available
         alternatives, if any, is recommended.</p>

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

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

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

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

         <p>The <url id="&url-bts;" name="Debian Bug Tracking System">
         often provides additional information on why the package was
         removed. You should review both the archived bug reports for the
         package itself and the archived bug reports for the <url
         id="&url-bts;cgi-bin/pkgreport.cgi?pkg=ftp.debian.org&#38;archive=yes"
         name="ftp.debian.org pseudo-package">.</p>

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

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

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

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

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

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

        <chapt id="information">
        <heading>Issues to be aware of for &releasename;</heading>
        
        <sect id="problems"><heading>Potential problems</heading>
          <p>Sometimes, changes have side-issues we cannot reasonably avoid,
          or we expose bugs somewhere else.
          We document here the issues we are aware of.
          Please also read the errata, the relevant packages' documentation,
          bug reports and other information mentioned in <ref id="morereading">.
          </p>

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

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

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

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

        </sect>


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

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

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

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

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

        </sect>
-->

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

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

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

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

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

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

<!-- 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-amd64 [
          <p>For some SATA disk controllers, the device assigned to a drive and
          its partitions may change from <file>/dev/hdX</file> to
          <file>/dev/sdX</file>. If this happens, you will have to modify your
          <file>/etc/fstab</file> and bootloader configuration accordingly.
          Unless these changes are made correctly, your system may not boot
          correctly<footnote>It will boot the kernel but will fail when trying
          to mount the root filesystem and will abort with an error <em>waiting for root filesystem</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 names newly assigned devices in the kernel boot messages or by reviewing
          the contents of <file>/dev/disk</file>.</footnote>.</p>
]]>

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

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

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

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

          <p>If your console keyboard is affected, you will probably also need to
          reconfigure your keyboard for the X Window System. You can do this
          either by running <tt>dpkg-reconfigure xserver-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>
]]> <!-- %not-amd64 -->

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

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

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

        </sect1>

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

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

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

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

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

        <p>As <package/udev/ is automatically installed as a dependency of the new
        default initrd generator used with the 2.6 kernels
        (<package/initramfs-tools/), upgrading to a 2.6 kernel will normally result
        in <package/udev/ being activated. You can avoid installing <package/udev/
        if you install an alternate initrd generator, such as <package/yaird/. 
        <package/initramfs-tools/ is the recommended initrd generator.</p>

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

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

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


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

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

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

      </sect>

      <sect id="exim"> <heading>Upgrading from exim to exim4</heading>
      <p>One of the packages that has been obsoleted by the &releasename;
      release is the Mail Transfer Agent (MTA) <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>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>

      </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 not to ship
        large functional changes in security updates.
        We cannot predict it today, but during lifetime of &releasename; the
        Debian Security Team may come to a point where supporting
        Mozilla products is no longer feasible and announce
        the end of security support for Mozilla products.
        You should take this into account when deploying Mozilla and consider
        alternatives available in Debian if the absence of security support would
        pose a problem for you.</p>
      </sect>

<!-- 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
        of 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 that 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 favourite IRC client at
        &debian-irc-server; and join #debian.</p>

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

      </sect1>
      </sect> 

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

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

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

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

      </sect>

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

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

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

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

    </chapt>

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

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

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

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

          <p>You should upgrade to the latest &oldreleasename; point release:
          r5, published February 2007.</p>

       </sect>

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

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

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

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

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

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

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

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

          to refresh the package list.</p>

       </sect>

    </appendix>

  </book>
</debiandoc>

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