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

<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
  <!entity % dynamicdata  SYSTEM "../dynamic.ent"       > %dynamicdata;
  <!entity % shareddata   SYSTEM "../release-notes.ent" > %shareddata;
  <!entity docid "$Id: release-notes.en.sgml,v 1.33 2005-05-18 23:48:21 fjp Exp $">
]>

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

<debiandoc>
  <book>
  <titlepag>
    <title>Release Notes for &debian; &release; (`&releasename'), &arch-title;</title>
      <author>
        <name>Josip Rodin, Bob Hilliard, Adam Di Carlo, Anne Bezemer, Rob
        Bradford (current)</name><email></email>
      </author>
      <author>
        <name></name><email>debian-doc@lists.debian.org</email>
      </author>
      <version>&docid;</version>
    </titlepag>
    <toc detail="sect1">
      <chapt id="about"><heading>What's new in the Release Notes</heading>
       
        <p>[The most recent version of this document is always available at
        <url id="&url-release-notes;">. If your version is more than a month
        old, you might wish to download the latest version.]</p>

        <p>Please note that previous editions of the release notes contained
        information about upgrading from releases older than than the previous
        release. However such content often complicated the documentation so we
        have decided to only discuss upgrades from &debian; 3.0 ('woody'). If
        you need to upgrade from older releases please read previous editions of
        the release notes.</p>

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

        <p>The list of supported architectures has not changed since the
        previous release, &debian; 3.0 ('woody'). Here is the full list of
        architectures for this release.</p>
        
        <p>
          <list>
            <item><p>Intel x86 ('i386')</p></item>
            <item><p>Motorola 680x0 ('m68k')</p></item>
            <item><p>Alpha ('alpha')</p></item>
            <item><p>SPARC ('sparc')</p></item>
            <item><p>PowerPC ('powerpc')</p></item>
            <item><p>ARM ('arm')</p></item>
            <item><p>MIPS ('mips' (Big endian) and 'mipsel' (Little endian))</p></item>
            <item><p>Intel Itanium ('ia64')</p></item>
            <item><p>HP PA-RISC ('hppa')</p></item>
            <item><p>S/390 ('s390')</p></item>
          </list>
        </p>

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

<![ %secondrelease [

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

]]>

          <p>&debian; &release; for the &arch-title; architecture ships with
          kernel version &kernelversion;.</p>
<![ %available-2.6 [
          
          <p>On the &arch-title; architecture a 2.6 kernel is also available,
          this has kernel version &kernelversion-2.6;. Note that Debian's 2.6.8
          kernel packages include the 2.6.8.1 kernel release and selected other
          patches.</p>
]]>
        
        <sect id="newdistro"><heading>What's new in the distribution?</heading> 
           
           <p>This new release of Debian again comes with a lot more software
           than its predecessor &oldreleasename;; the distribution includes
           over 9000 new packages. Most of the software in the distribution
           has been updated: almost 6500 software packages (that is 73% of
           the &oldreleasename; distribution). Also, a significant number of
           packages has for various reasons been removed from the distribution.
           You will not see any updates for these packages and they will be
           marked as 'obsolete' in package management front-ends.</p>

           <p>To replace the aging, much-maligned, yet still popular
           <package>dselect</package>, many apt frontends have been in
           development during the woody release cycle. Interested users
           should investigate the <package>aptitude</package> and
           <package>synaptic</package> packages.</p>
       
           <p>This release of &debian; contains the much improved XFree86
           4.3 release, which includes support for a greater range of
           hardware, better autodetection support, and improved support for
           advanced technologies such as Xinerama and 3D acceleration.</p>
           
           <p>&debian; is more desktop orientated than ever in this new release,
           it now includes GNOME 2.8 and KDE 3.3. Also included for the
           first time is a complete office suite in the form of OpenOffice.org
           1.1, other productivity tools included in the release are the
           Evolution groupware software and GAIM instant messaging client.</p>
           
           <p>The official &debian; distribution now ships on thirteen to fifteen
           binary CDs (depending on the architecture) and a similar number of
           source CDs. A DVD version of the distribution is now also available.</p>

        <sect1 id="volatile"><heading>New service debian-volatile</heading> 
           
           <p>There is a new service <em/debian-volatile/ allowing users to easily
           update stable packages that contain information that quickly goes out
           of date. Examples are a virus scanner's signatures list or a spam
           filter's pattern set. An administrator can use the "volatile.debian.net"
           archive with similar ease to the "security.debian.org" archive, and
           enjoy the use of packages with up-to-date information without the
           hassle and risks of maintaining an entire (or partial) system based
           on bleeding-edge packages. For more information and a list of mirrors,
�          please see the archive's <url id="&url-debian-volatile"
           name="web page">.</p>

        </sect1>
        </sect>

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

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

<![ %i386 [ 

          <p>Kernel images are available in various "flavours". These
          flavours each support a different set of hardware. The flavours
          available in &debian; &release; for &arch-title; are:</p>

          <p>
            <taglist>
              <tag>vanilla</tag>
              <item><p>The standard kernel package available in Debian. This
              includes almost all drivers supported by Linux built as
              modules. Including drivers for network devices, SCSI devices,
              sound cards, Video4Linux devices, etc. The
             `vanilla' flavour includes one boot, one root and two
              driver disks.</p></item>
              
              <tag>speakup</tag>
              <item><p>This is almost the same as the vanilla kernel above
              but with support for braille displays. A complete list of
              supported models may be found in the brltty documentation.
              This flavour includes one boot, one root and one driver floppy
              disk image.<p></item>
             
            </taglist>
<!-- FJP: I feel the info about floppies should be removed from this table as
          floppies are no longer the most used installation method. -->

          <p>The kernel config files for these flavours can be found in their
          respective directories in a file named 'kernel-config'.</p>

]]>

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

<![ %available-2.6 [
          <p>An installer using a 2.6 based kernel is available for
          &arch-title;. For more details on how to use it please consult the
          Installation Guide.</p>
]]>          
           
        </sect>

      </chapt>

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

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

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

        or on the Internet at: <url id="&url-install-manual;">.</p>

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

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

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

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

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

      </sect>

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

        <p>Because of display problems on some systems, framebuffer support is
        disabled by default for &arch-title;. This can result in ugly display on
        systems that do properly support the framebuffer, like those with ATI
        graphical cards. If you see display problems in the installer, you can try
        booting the installer with parameter "debian-installer/framebuffer=true".</p>

      </sect>
]]>

      </chapt>


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

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

1.3.1 or less i386
2.0           i386,m68k
2.1           i386,m68k,alpha,sparc
2.2           i386,m68k,alpha,sparc,powerpc,arm
3.0             + hppa s390 mips mipsel ia64
-->

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

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

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

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

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

          <p><em/Important/: You should <em/not/ upgrade using <prgn/telnet/,
          <prgn/rlogin/, <prgn/rsh/, or from an X session managed by <prgn/xdm/,
          <prgn/gdm/ or <prgn/kdm/ etc on the machine you are upgrading. That is
          because each of those services may well be terminated during the
          upgrade, which can result in an <em/inaccessible/ system that is only
          half-upgraded.</p>
          
          <p>The recommended method of upgrading is to use <prgn/aptitude/, as
          described here. The built-in dependency analysis enables smooth
          upgrades and easy installations.</p>
          
          <p>Any package installation operation must be run with superuser
          privileges, so either login as root or use <prgn/su/ or
          <prgn/sudo/ to gain the necessary access rights.</p>
          
          <p>First the <package>aptitude</package> package needs to be installed.
          This is done with:</p> 

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

          <p>Provided that you have a working APT configuration this will
          install the &oldreleasename; version of
          
          <prgn>aptitude</prgn>.</p>

<![ %glibcneedsnewkernel [

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

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

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

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

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

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

<![ %hppa [
          <p>On 64bit HPPA machines you will need to upgrade to a newer
          kernel version first before upgrading the system. This is because newer
          versions of glibc use assembler instructions not available on certain
          machines, so you need an updated kernel first that emulates the missing
          instructions.</p>
]]>
<![ %i386 [
          <p>True "80386" CPUs are <em/no longer supported/ by sarge.
          This does not affect any CPUs that are compatible with "80486"
          CPUs or above.</p>
]]>

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

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

          <p>Backports are available of all tools needed to install the
          current kernel from sarge. Detailed instructions on how to
          install the new kernel can be found in
          <ref id="kernel-upgrade-howto">.</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>
<!-- FJP: Couldn't the advise to hold such packages prevent the upgrade of e.g.
          libc6 if the package depends on the old version! -->

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

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

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

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

          or

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

          <p>It is desirable to remove any holds before upgrading. If any
          package that is essential for the upgrade is on hold, the upgrade
          will fail. You can identify packages on hold with
 
          <example>
# dpkg --audit
          </example></p>

          <p>If you changed and recompiled a package locally, and didn't rename
          it or put an epoch in the version, you must put it on hold to prevent
          it from being upgraded. The `hold' package state can be changed by
          using <prgn/aptitude/. With 
          
          <example>
aptitude hold | unhold &lt;package&gt;
          </example>
            </p>
        </sect1>

        <sect1><heading>Special considerations for SSH users</heading>

          <p>The commercial SSH located in the <package/ssh/ package before
          release 2.2 or in the <package/ssh-nonfree/ package in release 2.2 has
          been replaced by the DFSG free <package/ssh/ package (OpenSSH) in
          this release. The commercial SSH collection is no longer present. 
          The <package/ssh/ package includes a Debconf question which will
          regenerate a configuration which is OpenSSH compatible.</p>
          
        </sect1>
        </sect>

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

          <p>Before starting the upgrade you must set up <package/apt/'s
          configuration file for package lists,
          <file>/etc/apt/sources.list</file>.</p>
          
          <p><package/apt/ will consider all packages that can be found via
          any "<tt>deb</tt>" line, and install the package with the highest
          version number, giving priority to the first mentioned lines (that
          way, in case of multiple mirror locations, you'd typically first
          name a local harddisk, then CD-ROMs, and then HTTP/FTP
          mirrors).</p>

         <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>
<!-- FJP: 'Otherwise' does not refer back to anything here, so I deleted it
          (unless the intention was to refer to local intr_a_net HTTP
          servers in the previous para). -->

           <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/stable/main/binary-&architecture;/...
&url-debian-mirror-eg;/dists/stable/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 NFS-mounted).</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/stable/main/binary-&architecture;/...
/var/ftp/debian/dists/stable/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 stable 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</heading>

<!-- FJP: Are these instructions also valid for adding DVD's? -->

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

          <p>Make sure there is a line in <file>/etc/fstab</file> that
          enables mounting your CD-ROM drive at the <file>/cdrom</file>
          mount point (the exact <file>/cdrom</file> mount point is required
          for <prgn/apt-cdrom/). For example, if <file>/dev/hdc</file> is
          your CD-ROM drive, <file>/etc/fstab</file> should contain a line
          like:

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

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

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

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

          <p>Next, run:

          <example>
apt-cdrom add
          </example>

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

        <sect id="upgradingpackages"><heading>Upgrading packages</heading>
          
          <p>The recommended tool for upgrading between &debian; releases is
          to use the package management tool <prgn>aptitude</prgn>. This tool
          makes safer decisions about package installations than running
          <prgn>apt-get</prgn> directly.</p>
          
          <p>Don't forget to mount all needed partitions (notably the root
          and <file>/usr</file> partitions) read-write, with a command
          like:

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

          <p>Next ensure that the APT source entries (in
          <file>/etc/apt/sources.list</file>) refer to the <tt>'stable'</tt>
          distribution and do not refer to it by its codename (e.g.
          <tt>&oldreleasename;</tt>).
          
          <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 any problems develop, you will have a log of
          what happened, and if needed, can provide exact information in a bug
          report. To start the recording, type:

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

          or similar. Do not put the typescript file in a temporary
          directory such as <file>/tmp</file> or <file>/var/tmp</file> (files
          in those directories may be deleted during the upgrade or during any
          restart).</p>
 
          <p>First <prgn>aptitude</prgn> needs to fetch a list of new and
          updated packages for the new release. This is done by executing:</p>
          
          <p><example>
aptitude update
          </example></p>

          <p>Once <prgn>aptitude</prgn> has information on all the available
          packages, the system is almost ready to be fully upgraded. First
          however the <package>doc-base</package> package must be upgraded
          <em>if it is installed</em>. You can find out if it is installed
          using:</p>
          
          <p><example>
dpkg -l doc-base
          </example></p>

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

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

          <p>This will perform a complete upgrade of the system, i.e.  install
          the newest available versions of all packages, and resolve all
          possible dependency changes between packages in different releases.
          If necessary, it will install some new packages (usually new library
          versions, or renamed packages), and remove any conflicting obsoleted
          packages (such as <package>console-tools-libs</package>).</p>

          <p>When upgrading from a set of CD-ROMs, you will be asked to
          insert specific CDs at several points during the upgrade. You
          might have to insert the same CD multiple times; this is due to
          inter-related packages that have been spread out over the CDs.</p>
   
          <p>New versions of currently installed packages that cannot be
          upgraded without changing the install status of another package will
          be left at their current version (displayed as "held back"). This can
          be resolved by either using <prgn>aptitude</prgn> to choose these
          packages for installation or by trying <tt>aptitude -f install
          &lt;package&gt;</tt>.</p>
            
          <p>The <tt/--fix-broken/ (or just <tt/-f/) option causes
          <package/apt/ to attempt to correct a system with broken
          dependencies in place. <package/apt/ does not allow broken package
          dependencies to exist on a system.</p>

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

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

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

          <example>
dpkg --remove <var>packagename</var>
          </example>

          to eliminate some of the offending packages, or
 
          <example>
aptitude --fix-broken install
dpkg --configure --pending
          </example></p>

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

          <example>
dpkg --install /path/to/packagename.deb
          </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>

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

          <p>When <tt>aptitude dist-upgrade</tt> has finished, the
          "formal" upgrade is complete, but there are some other things
          that should be taken care of <em/before/ the next reboot.</p>
          
  <p>Read
          <file>/usr/share/doc/xfree86-common/README.Debian-upgrade</file> for
          more info on the upgrade of the X window system packages. This is
          relevant for users of all previous Debian releases. In short, you
          need to read it.</p>

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

          <![ %available-2.6 [

         <p>&debian; comes with a &kernelversion; kernel which is in the 2.4
         series, the older stable Linux kernel series. You may wish to use a 2.6
         series kernel for better hardware support or improved performance.</p>
         
]]>
         
         <p>To upgrade your kernel you must first choose the kernel most
         appropriate for your subarchitecture. A list of kernels available for
         you to install can be found with:
<!-- FJP: s/subarchitecture/subarchitecture and processor/ ??? -->

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

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

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

      </chapt>

        <chapt id="information"><heading>Detailed changes to the system</heading>

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

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

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

          <p><em>No changes yet reported.</em></p>
        
        </sect>
-->
<sect id="pythonchanges"><heading>Changes to Python packages</heading>

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

<![ %not-s390 [
        <sect id="kernel_update">
        <heading>Keyboard issues on upgrades to a 2.6 kernel</heading>

          <p>After the upgrade to &releasename;, you may have 2.6 kernel images
          available for installation. There is an important change in the
          input layer for 2.6 kernels that you should be aware of before you
          attempt to switch from using a 2.4 to a 2.6 kernel.</p>

          <p>The change in the input layer 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 'dpkg-reconfigure console-data', choosing
          the option "Select keymap from full list" and selecting a "pc"
          keyboard.</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>
]]>
        </sect>
]]>

        </chapt>

      <chapt id="moreinfo">

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

        <sect id="morereading"> <heading>Further reading</heading>
        <p>Beyond these release notes and the installation guide further
        documentation on &debian; is available from the Debian
        Documentation Project (DDP), whose goal is to create high quality
        documentation for Debian users and developers. Documentation
        including the Debian Guide, Debian New Maintainers Guide, and Debian
        FAQ are available, and many more. For full details of the resources
        available see the DDP website at <url
        id="&url-ddp;">.</p>
 
        <p>Documentation for individual packages is installed into
        <file>/usr/share/doc/<var>package</var></file>, this may include
        copyright information, Debian specific details and any upstream
        documentation.</p>
 
      </sect> 
      
      <sect id="gethelp"> 
        <heading>Getting help</heading> 
      
        <p>There are many sources of help, advice and support for Debian
        users, but these should only be considered if research into
        documentation of the issue has exhausted all sources. This section
        provides a short introduction into these which may be helpful for
        new Debian users.</p>
        
      <sect1 id="lists">
        <heading>Mailing lists</heading>
        <p>The mailing lists of most interest to Debian users are the
        debian-user list (English) and other debian-user-<var/language/ lists
        (for other languages). For information on these lists and details of
        how to subscribe see <url id="&url-debian-list-archives;">. Please
        check the archives for answers to your question prior to posting and
        also adhere to standard list etiquette.</p>
      </sect1>

      <sect1 id="irc">
        <heading>Internet Relay Chat</heading> 
        
        <p>Debian has an IRC channel dedicated to the support and aid of
        Debian users located on the Freenode IRC network which exists to
        provide interactive services to peer-directed project communities.
        To access the channel point your favourite IRC client at
        &debian-irc-server; and join #debian.</p>
        
        <p>Please follow the channel guidelines, respecting other users
        fully. For more information on Freenode please visit the <url
        id="&url-irc-host;" name="website">.</p>

      </sect1>
      </sect> 

      <sect id="bugs">
        <heading>Reporting bugs</heading>
        
        <p>We strive to make Debian GNU/Linux a high quality operating
        system, however that does not mean that the packages we provide are
        totally free of bugs. As our service to our users we provide all the
        information on reported bugs at our own Bug Tracking System (BTS)
        browseable at <url id="&url-bts;" name="bugs.debian.org">, this is
        consistent with Debian's open development.</p>
<!-- FJP: I propose to replace the last sentence by:
        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>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> in any installed system) or
        online at the <url id="&url-bts;" name="Bug Tracking
        System">.</p>
<!-- FJP: The 'bug' program and package are obsolete. -->
<!-- JFS: The reference cards are only available if you have doc-debian installed, which might not always be the case -->

      </sect>

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

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

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

    </chapt>


<![ %upgradekernel [

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

          <p><strong>The information in this appendix is relevant only for
          if, for a successful upgrade of the system, you need to upgrade the
          kernel <em/before/ upgrading the system. Please read
          <ref id="new-kernel"> to find out if that is required for your
          system</strong>.</p>

          <p>The following instructions explain step by step how to use the
          available backported tools to install the newer kernel.</p>

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

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

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

<![ %sparc [
               Then install the packages
               <package>kernel-image-2.4.27-2-sparc32</package>,
               <package>modutils</package> and
               <package>initrd-tools</package>.
]]>
<![ %hppa [
               Then install the packages
               <package>kernel-image-2.6.8-2-64</package>,
               <package>module-init-tools</package> and
               <package>initrd-tools</package>.
]]>
               </p>
               <p><em>with dpkg</em>: to install the packages directly with <prgn>dpkg</prgn> you need to
               download the necessary files first.
<![ %hppa [
<!-- note: download URLs not final yet -->
               <p><list>
                 <item><url id="http://ftp.debian.org/debian/pool/main/k/kernel-image-2.6.8-hppa/kernel-image-2.6.8-2-64_2.6.8-6_hppa.deb"></item>
                 <item><url id="&deb-kernel-upgrade;/module-init-tools_3.2-pre1-2.woody1_hppa.deb">
                 <item><url id="&deb-kernel-upgrade;/initrd-tools_0.1.79-0.woody1_all.deb">
                 <item><url id="&deb-kernel-upgrade;/cramfsprogs_1.1-6.woody1_hppa.deb">
               </list></p>

               <p>The kernel package depends on <package>module-init-tools</package>;
               <package>initrd-tools</package> depends on <package>cramfsprogs</package>.
               All other dependencies can be satisfied with packages from
               &oldreleasename; in the usual way.</p>
]]>

<![ %sparc [
               <p><list>
                 <item><url id="http://ftp.debian.org/debian/pool/main/k/kernel-image-2.4.27-sparc/kernel-image-2.4.27-2-sparc32_2.4.27-2_sparc.deb">
                 <item><url id="&deb-kernel-upgrade;/modutils_2.4.26-1.2woody1_sparc.deb">
                 <item><url id="&deb-kernel-upgrade;/initrd-tools_0.1.77-0.woody1_all.deb">
                 <item><url id="&deb-kernel-upgrade;/cramfsprogs_1.1-6.woody1_sparc.deb">
               </list></p>

               <p>The kernel package depends on <package>modutils</package>.
               <package>initrd-tools</package> depends on <package>cramfsprogs</package>.
               All other dependencies can be satisfied with packages from
               &oldreleasename; in the usual way.</p>
]]>
               </item>

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

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

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

          </taglist></p>

    </appendix>
]]>

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