[install-guide/F21-rewrite] Better structure in Troubleshooting
pbokoc
pbokoc at fedoraproject.org
Sun Sep 7 19:21:24 UTC 2014
commit 88d9ad2166256c7a8ef59bbd98b494888ac941d8
Author: Petr Bokoc <pbokoc at redhat.com>
Date: Sun Sep 7 21:20:45 2014 +0200
Better structure in Troubleshooting
en-US/Troubleshooting.xml | 340 ++++++++++++++++++++++++---------------------
1 files changed, 180 insertions(+), 160 deletions(-)
---
diff --git a/en-US/Troubleshooting.xml b/en-US/Troubleshooting.xml
index 98e4417..555a28e 100644
--- a/en-US/Troubleshooting.xml
+++ b/en-US/Troubleshooting.xml
@@ -7,189 +7,209 @@
<chapter id="chap-troubleshooting">
<title>Troubleshooting</title>
<para>
- This chapter discusses some common installation problems and their solutions.
+ This chapter offers some pointers on how to get help when something goes wrong. It also discusses some common installation problems and their solutions.
</para>
- <section id="chap-troubleshooting-log-files">
- <title>Log Files Generated During the Installation</title>
+ <section id="sect-troubleshooting-getting-help">
+ <title>Getting Help</title>
<para>
- For debugging purposes, <application>Anaconda</application> logs installation actions into files in the <filename>/tmp</filename> directory. These files are listed in the following table.
+ text about ask.fedora.com, stackexchange, phoronix etc.
</para>
- <table id="tabl-installation-log-files">
- <title>Log Files and Their Contents</title>
- <tgroup cols="2">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="2*" />
- <thead>
- <row>
- <entry>
- Log file
- </entry>
- <entry>
- Contents
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <filename>/tmp/anaconda.log</filename>
- </entry>
- <entry>
- general <application>Anaconda</application> messages
- </entry>
- </row>
- <row>
- <entry>
- <filename>/tmp/program.log</filename>
- </entry>
- <entry>
- all external programs run during the installation
- </entry>
- </row>
- <row>
- <entry>
- <filename>/tmp/storage.log</filename>
- </entry>
- <entry>
- extensive storage module information
- </entry>
- </row>
- <row>
- <entry>
- <filename>/tmp/packaging.log</filename>
- </entry>
- <entry>
- <application>yum</application> and <application>rpm</application> package installation messages
- </entry>
- </row>
- <row>
- <entry>
- <filename>/tmp/syslog</filename>
- </entry>
- <entry>
- hardware-related system messages
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- If the installation fails, the messages from these files are consolidated into <filename>/tmp/anaconda-tb-<replaceable>identifier</replaceable></filename>, where <replaceable>identifier</replaceable> is a random string.
- </para>
- <para>
- All of the files listed above reside in the installation program's RAM disk, which means they are not saved permamently and will be lost once the system is powered down. To store them permanently, copy those files to another system on the network using <command>scp</command> on the system running the installation program, or copy them to a mounted storage device (such as an USB flash drive). Details on how to transfer the log files are below. Note that if you use an USB flash drive or other removable media, you should make sure to back up any data on it before starting the procedure.
- </para>
- <procedure>
- <title>Transferring Log Files Onto a USB Drive</title>
- <step>
- <para>
- On the system you are installing, press <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to access a shell prompt. You will be logged into a root account and you will have access to the installation program's temporary file system.
- </para>
- </step>
- <step>
- <para>
- Connect a USB flash drive to the system and execute the <command>dmesg</command> command. A log detailing all recent events will be displayed. At the bottom of this log, you will see a set of messages caused by the USB flash drive you just connected. It will look like a set of lines similar to the following:
- </para>
- <screen>
+
+ <section id="sect-troubleshooting-log-files">
+ <title>Log Files Generated During the Installation</title>
+ <para>
+ For debugging purposes, <application>Anaconda</application> logs installation actions into files in the <filename>/tmp</filename> directory. These files are listed in the following table.
+ </para>
+ <table id="tabl-installation-log-files">
+ <title>Log Files and Their Contents</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colwidth="1*" />
+ <colspec colname="c2" colwidth="2*" />
+ <thead>
+ <row>
+ <entry>
+ Log file
+ </entry>
+ <entry>
+ Contents
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <filename>/tmp/anaconda.log</filename>
+ </entry>
+ <entry>
+ general <application>Anaconda</application> messages
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename>/tmp/program.log</filename>
+ </entry>
+ <entry>
+ all external programs run during the installation
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename>/tmp/storage.log</filename>
+ </entry>
+ <entry>
+ extensive storage module information
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename>/tmp/packaging.log</filename>
+ </entry>
+ <entry>
+ <application>yum</application> and <application>rpm</application> package installation messages
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename>/tmp/syslog</filename>
+ </entry>
+ <entry>
+ hardware-related system messages
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ If the installation fails, the messages from these files are consolidated into <filename>/tmp/anaconda-tb-<replaceable>identifier</replaceable></filename>, where <replaceable>identifier</replaceable> is a random string.
+ </para>
+ </section>
+
+ <section id="sect-troubleshooting-transferring-logs">
+ <title>Transferring Log Files from the Installation System</title>
+ <para>
+ All of the files described in <xref linkend="sect-troubleshooting-log-files" /> reside in the installation program's RAM disk, which means they are not saved permamently and will be lost once the system is powered down. To store them permanently, copy those files to another system on the network using <command>scp</command> on the system running the installation program, or copy them to a mounted storage device (such as an USB flash drive). Details on how to transfer the log files are below. Note that if you use an USB flash drive or other removable media, you should make sure to back up any data on it before starting the procedure.
+ </para>
+
+ <section id="sect-troubleshooting-transferring-logs-usb">
+ <title>Transferring Log Files Onto a USB Drive</title>
+ <procedure>
+ <step>
+ <para>
+ On the system you are installing, press <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to access a shell prompt. You will be logged into a root account and you will have access to the installation program's temporary file system.
+ </para>
+ </step>
+ <step>
+ <para>
+ Connect a USB flash drive to the system and execute the <command>dmesg</command> command. A log detailing all recent events will be displayed. At the bottom of this log, you will see a set of messages caused by the USB flash drive you just connected. It will look like a set of lines similar to the following:
+ </para>
+ <screen>
<computeroutput>[ 170.171135] sd 5:0:0:0: [sdb] Attached SCSI removable disk</computeroutput>
- </screen>
- <para>
- Note the name of the connected device - in the above example, it is <literal>sdb</literal>.
- </para>
- </step>
- <step>
- <para>
- Go to the <filename>/mnt</filename> directory and once there, create new directory which will serve as the mount target for the USB drive. The name of the directory does not matter; this example uses the name <literal>usb</literal>.
- </para>
- <screen>
+ </screen>
+ <para>
+ Note the name of the connected device - in the above example, it is <literal>sdb</literal>.
+ </para>
+ </step>
+ <step>
+ <para>
+ Go to the <filename>/mnt</filename> directory and once there, create new directory which will serve as the mount target for the USB drive. The name of the directory does not matter; this example uses the name <literal>usb</literal>.
+ </para>
+ <screen>
<prompt>#</prompt> <command>mkdir usb</command>
- </screen>
- </step>
- <step>
- <para>
- Mount the USB flash drive onto the newly created directory. Note that in most cases, you do not want to mount the whole drive, but a partition on it. Therefore, do not use the name <literal>sdb</literal> - use the name of the partition you want to write the log files to. In this example, the name <literal>sdb1</literal> is used.
- </para>
- <screen>
+ </screen>
+ </step>
+ <step>
+ <para>
+ Mount the USB flash drive onto the newly created directory. Note that in most cases, you do not want to mount the whole drive, but a partition on it. Therefore, do not use the name <literal>sdb</literal> - use the name of the partition you want to write the log files to. In this example, the name <literal>sdb1</literal> is used.
+ </para>
+ <screen>
<prompt>#</prompt> <command>mount /dev/sdb1 /mnt/usb</command>
- </screen>
- <para>
- You can now verify that you mounted the correct device and partition by accessing it and listing its contents - the list should match what you expect to be on the drive.
- </para>
- <screen>
+ </screen>
+ <para>
+ You can now verify that you mounted the correct device and partition by accessing it and listing its contents - the list should match what you expect to be on the drive.
+ </para>
+ <screen>
<prompt>#</prompt> <command>cd /mnt/usb</command>
- </screen>
- <screen>
+ </screen>
+ <screen>
<prompt>#</prompt> <command>ls</command>
- </screen>
- </step>
- <step>
- <para>
- Copy the log files to the mounted device.
- </para>
- <screen>
+ </screen>
+ </step>
+ <step>
+ <para>
+ Copy the log files to the mounted device.
+ </para>
+ <screen>
<prompt>#</prompt> <command>cp /tmp/*log /mnt/usb</command>
- </screen>
- </step>
- <step>
- <para>
- Unmount the USB flash drive. If you get an error message saying that the target is busy, change your working directory to outside the mount (for example, <filename>/</filename>).
- </para>
- <screen>
+ </screen>
+ </step>
+ <step>
+ <para>
+ Unmount the USB flash drive. If you get an error message saying that the target is busy, change your working directory to outside the mount (for example, <filename>/</filename>).
+ </para>
+ <screen>
<prompt>#</prompt> <command>umount /mnt/usb</command>
- </screen>
- </step>
- </procedure>
- <para>
- The log files from the installation are now saved on the USB flash drive.
- </para>
-
- <procedure>
- <title>Transferring Log Files Over the Network</title>
- <step>
+ </screen>
+ </step>
+ </procedure>
<para>
- On the system you are installing, press <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to access a shell prompt. You will be logged into a root account and you will have access to the installation program's temporary file system.
+ The log files from the installation are now saved on the USB flash drive.
</para>
- </step>
- <step>
- <para>
- Switch to the <filename class="directory">/tmp</filename> directory where the log files are located:
- </para>
- <screen>
+ </section>
+
+ <section id="sect-troubleshooting-transferring-logs-network">
+ <title>Transferring Log Files Over the Network</title>
+ <procedure>
+ <step>
+ <para>
+ On the system you are installing, press <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to access a shell prompt. You will be logged into a root account and you will have access to the installation program's temporary file system.
+ </para>
+ </step>
+ <step>
+ <para>
+ Switch to the <filename class="directory">/tmp</filename> directory where the log files are located:
+ </para>
+ <screen>
<prompt>#</prompt> <command>cd /tmp</command>
- </screen>
- </step>
- <step>
- <para>
- Copy the log files onto another system on the network using the <command>scp</command> command:
- </para>
- <screen>
+ </screen>
+ </step>
+ <step>
+ <para>
+ Copy the log files onto another system on the network using the <command>scp</command> command:
+ </para>
+ <screen>
<prompt>#</prompt> <command>scp *log <replaceable>user</replaceable>@<replaceable>address</replaceable>:<replaceable>path</replaceable></command>
- </screen>
- <para>
- Replace <replaceable>user</replaceable> with a valid user name on the target system, <replaceable>address</replaceable> with the target system's address or host name, and <replaceable>path</replaceable> with the path to the directory you wish to save the log files into. For example, if you want to log in as <systemitem class="username">john</systemitem> to a system with an IP address of <systemitem>192.168.0.122</systemitem> and place the log files into the <filename class="directory">/home/john/logs/</filename> directory on that system, the command will have the following form:
- </para>
- <screen>
+ </screen>
+ <para>
+ Replace <replaceable>user</replaceable> with a valid user name on the target system, <replaceable>address</replaceable> with the target system's address or host name, and <replaceable>path</replaceable> with the path to the directory you wish to save the log files into. For example, if you want to log in as <systemitem class="username">john</systemitem> to a system with an IP address of <systemitem>192.168.0.122</systemitem> and place the log files into the <filename class="directory">/home/john/logs/</filename> directory on that system, the command will have the following form:
+ </para>
+ <screen>
<prompt>#</prompt> <command>scp *log john at 192.168.0.122:/home/john/logs/</command>
- </screen>
- <para>
- When connecting to the target system for the first time, you may encounter a message similar to the following:
- </para>
- <screen>
+ </screen>
+ <para>
+ When connecting to the target system for the first time, you may encounter a message similar to the following:
+ </para>
+ <screen>
<computeroutput>The authenticity of host '192.168.0.122 (192.168.0.122)' can't be established.</computeroutput>
<computeroutput>ECDSA key fingerprint is a4:60:76:eb:b2:d0:aa:23:af:3d:59:5c:de:bb:c4:42.</computeroutput>
<computeroutput>Are you sure you want to continue connecting (yes/no)?</computeroutput>
- </screen>
+ </screen>
+ <para>
+ Type <literal>yes</literal> and press <keycap>Enter</keycap> to continue. Then, provide a valid password when prompted. The files will start transferring to the specified directory on the target system.
+ </para>
+ </step>
+ </procedure>
<para>
- Type <literal>yes</literal> and press <keycap>Enter</keycap> to continue. Then, provide a valid password when prompted. The files will start transferring to the specified directory on the target system.
+ The log files from the installation are now permanently saved on the target system and available for review.
</para>
- </step>
- </procedure>
- <para>
- The log files from the installation are now permanently saved on the target system and available for review.
- </para>
+ </section>
+
+ </section>
+
</section>
+
+
<section id="sect-troubleshooting-problems-beginning-installation">
<title>Trouble Beginning the Installation</title>
More information about the docs-commits
mailing list