move manual to top-level directory, split out of debian-installer package

1 files changed, 274 insertions, 0 deletions

diff --git a/en/boot-installer/trouble.xml b/en/boot-installer/trouble.xml
new file mode 100644
index 000000000..0553914b8
--- /dev/null
+++ b/en/boot-installer/trouble.xml
@@ -0,0 +1,274 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+ <sect1 id="boot-troubleshooting">
+ <title>Troubleshooting the Installation Process</title>
+<para>
+</para>
+
+  <sect2 condition="supports-floppy-boot" id="unreliable-floppies">
+  <title>Floppy Disk Reliability</title>
+
+<para>
+
+The biggest problem for people using floppy disks to install Debian
+seems to be floppy disk reliability.
+
+</para><para>
+
+The boot floppy is the floppy with the worst problems, because it
+is read by the hardware directly, before Linux boots.  Often, the
+hardware doesn't read as reliably as the Linux floppy disk driver, and
+may just stop without printing an error message if it reads incorrect
+data. There can also be failures in the Driver Floppies most of which
+indicate themselves with a flood of messages about disk I/O errors.
+
+</para><para>
+
+If you are having the installation stall at a particular floppy, the
+first thing you should do is re-download the floppy disk image and
+write it to a <emphasis>different</emphasis> floppy. Simply
+reformatting the old
+floppy may not be sufficient, even if it appears that the floppy was
+reformatted and written with no errors. It is sometimes useful to try
+writing the floppy on a different system.
+
+</para><para>
+
+One user reports he had to write the images to floppy
+<emphasis>three</emphasis> times before one worked, and then
+everything was fine with the third floppy.
+
+</para><para>
+
+Other users have reported that simply rebooting a few times with the
+same floppy in the floppy drive can lead to a successful boot. This is
+all due to buggy hardware or firmware floppy drivers.
+
+</para>
+  </sect2>
+
+  <sect2><title>Boot Configuration</title>
+
+<para>
+
+If you have problems and the kernel hangs during the boot process,
+doesn't recognize peripherals you actually have, or drives are not
+recognized properly, the first thing to check is the boot parameters,
+as discussed in <xref linkend="boot-parms"/>.
+
+</para><para>
+
+If you are booting with your own kernel instead of the one supplied
+with the installer, be sure that <userinput>CONFIG_DEVFS</userinput> is set in
+your kernel.  The installer requires
+<userinput>CONFIG_DEVFS</userinput>.
+
+</para><para>
+
+Often, problems can be solved by removing add-ons and peripherals, and
+then trying booting again.  <phrase arch="i386">Internal modems, sound
+cards, and Plug-n-Play devices can be especially problematic.</phrase>
+
+</para><para>
+
+If you have a large amount of memory installed in your machine, more
+than 512M, and the installer hangs when booting the kernel, you may
+need to include a boot argument to limit the amount of memory the
+kernel sees, such as <userinput>mem=512m</userinput>.
+
+</para>
+  </sect2>
+
+  <sect2 arch="i386" id="i386-boot-problems">
+  <title>Common &arch-title; Installation Problems</title>
+<para>
+
+There are some common installation problems that can be solved or avoided by
+passing certain boot parameters to the installer.
+
+</para><para>
+
+Some systems have floppies with <quote>inverted DCLs</quote>. If you receive
+errors reading from the floppy, even when you know the floppy is good,
+try the parameter <userinput>floppy=thinkpad</userinput>.
+
+</para><para>
+
+On some systems, such as the IBM PS/1 or ValuePoint (which have ST-506
+disk drivers), the IDE drive may not be properly recognized.  Again,
+try it first without the parameters and see if the IDE drive is
+recognized properly.  If not, determine your drive geometry
+(cylinders, heads, and sectors), and use the parameter
+<userinput>hd=<replaceable>cylinders</replaceable>,<replaceable>heads</replaceable>,<replaceable>sectors</replaceable></userinput>.
+
+</para><para>
+
+If you have a very old machine, and the kernel hangs after saying
+<computeroutput>Checking 'hlt' instruction...</computeroutput>, then
+you should try the <userinput>no-hlt</userinput> boot argument, which
+disables this test.
+
+</para><para>
+
+If your screen begins to show a weird picture while the kernel boots,
+eg. pure white, pure black or colored pixel garbage, your system may
+contain a problematic video card which does not switch to the
+framebuffer mode properly.  Then you can use the boot parameter
+<userinput>debian-installer/framebuffer=false</userinput> or
+<userinput>video=vga16:off</userinput> to disable the framebuffer
+console. Only the English
+language will be available during the installation due to limited
+console features. See <xref linkend="boot-parms"/> for details.
+
+</para>
+
+  <sect3>
+  <title>System Freeze During the PCMCIA Configuration Phase</title>
+<para>
+
+Some laptop models produced by Dell are known to crash when PCMCIA device
+detection tries to access some hardware addresses. Other laptops may display
+similar problems. If you experience such a problem and you don't need PCMCIA
+support during the installation, you can disable PCMCIA using the
+<userinput>hw-detect/start_pcmcia=false</userinput> boot parameter. You can
+then configure PCMCIA after the installation is completed and exclude the
+resource range causing the problems.
+
+</para><para>
+
+Alternatively, you can boot the installer in expert mode. You will
+then be asked to enter the resource range options your hardware
+needs. For example, if you have one of the Dell laptops mentioned
+above, you should enter <userinput>exclude port
+0x800-0x8ff</userinput> here. There is also a list of some common
+resource range options in the <ulink
+url="http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-HOWTO-1.html#ss1.12">System
+resource settings section of the PCMCIA HOWTO</ulink>. Note that you
+have to omit the commas, if any, when you enter this value in the
+installer.
+
+</para>
+   </sect3>
+
+   <sect3>
+   <title>System Freeze while Loading the USB Modules</title>
+<para>
+
+The kernel normally tries to install USB modules and the USB keyboard driver
+in order to support some non-standard USB keyboards. However, there are some
+broken USB systems where the driver hangs on loading. A possible workaround
+may be disabling the USB controller in your mainboard BIOS setup. Another option
+is passing the <userinput>debian-installer/probe/usb=false</userinput> parameter
+at the boot prompt, which will prevent the modules from being loaded.
+
+</para>
+   </sect3>
+  </sect2>
+
+  <sect2 id="kernel-msgs">
+  <title>Interpreting the Kernel Startup Messages</title>
+
+<para>
+
+During the boot sequence, you may see many messages in the form
+<computeroutput>can't find <replaceable>something</replaceable>
+</computeroutput>, or <computeroutput>
+<replaceable>something</replaceable> not present</computeroutput>,
+<computeroutput>can't initialize <replaceable>something</replaceable>
+</computeroutput>, or even <computeroutput>this driver release depends
+on <replaceable>something</replaceable> </computeroutput>.
+Most of these messages are harmless. You
+see them because the kernel for the installation system is built to
+run on computers with many different peripheral devices. Obviously, no
+one computer will have every possible peripheral device, so the
+operating system may emit a few complaints while it looks for
+peripherals you don't own. You may also see the system pause for a
+while. This happens when it is waiting for a device to respond, and
+that device is not present on your system. If you find the time it
+takes to boot the system unacceptably long, you can create a
+custom kernel later (see <xref linkend="kernel-baking"/>).
+
+</para>
+  </sect2>
+
+
+  <sect2 id="problem-report">
+  <title>Bug Reporter</title>
+<para>
+
+If you get through the initial boot phase but cannot complete the
+install, the bug reporter menu choice may be helpful. It copies system
+error logs and configuration information to a user-supplied floppy.
+This information may provide clues as to what went wrong and how to
+fix it.  If you are submitting a bug report you may want to attach
+this information to the bug report.
+
+</para><para>
+
+Other pertinent installation messages may be found in
+<filename>/var/log/</filename> during the
+installation, and <filename>/var/log/debian-installer/</filename>
+after the computer has been booted into the installed system.
+
+</para>
+  </sect2>
+
+  <sect2 id="submit-bug">
+  <title>Submitting Installation Reports</title>
+<para>
+
+If you still have problems, please submit an installation report. We also
+encourage installation reports to be sent even if the installation is
+successful, so that we can get as much information as possible on the largest
+number of hardware configurations. Please use this template when filling out
+installation reports, and file the report as a bug report against the
+<classname>installation-reports</classname> pseudo package, by sending it to
+<email>submit@bugs.debian.org</email>.
+
+<informalexample><screen>
+Package: installation-reports
+
+Debian-installer-version: &lt;Fill in date and from where you got the image&gt;
+uname -a: &lt;The result of running uname -a on a shell prompt&gt;
+Date: &lt;Date and time of the install&gt;
+Method: &lt;How did you install?  What did you boot off?  If network
+      install, from where?  Proxied?&gt;
+
+Machine: &lt;Description of machine (eg, IBM Thinkpad R32)&gt;
+Processor:
+Memory:
+Root Device: &lt;IDE?  SCSI?  Name of device?&gt;
+Root Size/partition table: &lt;Feel free to paste the full partition
+      table, with notes on which partitions are mounted where.&gt;
+Output of lspci and lspci -n:
+
+Base System Installation Checklist:
+[O] = OK, [E] = Error (please elaborate below), [ ] = didn't try it
+
+Initial boot worked:    [ ]
+Configure network HW:   [ ]
+Config network:         [ ]
+Detect CD:              [ ]
+Load installer modules: [ ]
+Detect hard drives:     [ ]
+Partition hard drives:  [ ]
+Create file systems:    [ ]
+Mount partitions:       [ ]
+Install base system:    [ ]
+Install boot loader:    [ ]
+Reboot:                 [ ]
+
+Comments/Problems:
+
+&lt;Description of the install, in prose, and any thoughts, comments
+      and ideas you had during the initial install.&gt;
+</screen></informalexample>
+
+In the bug report, describe what the problem is, including the last
+visible kernel messages in the event of a kernel hang.  Describe the
+steps that you did which brought the system into the problem state.
+
+</para>
+  </sect2>
+ </sect1>