[install-guide/F21-rewrite] Putting back Troubleshooting
pbokoc
pbokoc at fedoraproject.org
Sun Sep 7 19:21:14 UTC 2014
commit 2496c8bfffbba338abaddc5b35c695bcb16a5974
Author: Petr Bokoc <pbokoc at redhat.com>
Date: Sun Sep 7 20:50:00 2014 +0200
Putting back Troubleshooting
en-US/Troubleshooting.xml | 714 +++++++++++++++++++++++++++++++++++++++++++--
1 files changed, 689 insertions(+), 25 deletions(-)
---
diff --git a/en-US/Troubleshooting.xml b/en-US/Troubleshooting.xml
index 4ff814c..a2f2a7a 100644
--- a/en-US/Troubleshooting.xml
+++ b/en-US/Troubleshooting.xml
@@ -3,31 +3,695 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "Installation_Guide.ent">
%BOOK_ENTITIES;
]>
+
<chapter id="chap-troubleshooting">
- <title>Troubleshooting</title>
- <para>
- intro text
- </para>
-
- <section id="sect-troubleshooting-starting-installation">
- <title>Problems Starting the Installation</title>
- <para>
- text
- </para>
- </section>
-
- <section id="sect-troubleshooting-during-installation">
- <title>Problems During the Installation</title>
- <para>
- text
- </para>
- </section>
-
- <section id="sect-troubleshooting-after-installation">
- <title>Problems After the Installation</title>
- <para>
- text
- </para>
- </section>
+ <title>Troubleshooting</title>
+ <para>
+ This chapter discusses some common installation problems and their solutions.
+ </para>
+
+ <section id="chap-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>
+ <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>
+<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>
+<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>
+<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>
+<prompt>#</prompt> <command>cd /mnt/usb</command>
+ </screen>
+ <screen>
+<prompt>#</prompt> <command>ls</command>
+ </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>
+<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>
+ <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>
+<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>
+<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>
+<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>
+ <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>
+ The log files from the installation are now permanently saved on the target system and available for review.
+ </para>
+ </section>
+
+ <section id="sect-troubleshooting-problems-beginning-installation">
+ <title>Trouble Beginning the Installation</title>
+
+ <section>
+ <title>Problems with Booting into the Graphical Installation</title>
+ <para>
+ Systems with some video cards have trouble booting into the graphical installation program. If the installation program does not run using its default settings, it attempts to run in a lower resolution mode. If that still fails, the installation program attempts to run in text mode.
+ </para>
+ <para>
+ There are several possible solutions to display issues, most of which involve specifying custom boot options. For more information, see <xref linkend="sect-boot-options-installer" />.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Use the basic graphics mode</term>
+ <listitem>
+ <para>
+ You can attempt to perform the installation using the basic graphics driver. To do this, edit the installation program's boot options and append <option>inst.xdriver=vesa</option> at the end of the command line.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Specify the display resolution manually</term>
+ <listitem>
+ <para>
+ If the installation program fails to detect your screen resolution, you can override the automatic detection and specify it manually. To do this, append the <option>inst.resolution=<replaceable>x</replaceable></option> option at the boot menu, where <replaceable>x</replaceable> is your display's resolution (for example, <literal>1024x768</literal>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Use an alternate video driver</term>
+ <listitem>
+ <para>
+ You can also attempt to specify a custom video driver, overriding the installation program's automatic detection. To specify a driver, use the <option>inst.xdriver=<replaceable>x</replaceable></option> option, where <replaceable>x</replaceable> is the device driver you want to use (for example, <literal>nouveau</literal>).
+ </para>
+ <note>
+ <para>
+ If specifying a custom video driver solves your problem, you should report it as a bug at <ulink url="https://bugzilla.redhat.com" /> under the <literal>anaconda</literal> component. <application>Anaconda</application> should be able to detect your hardware automatically and use the appropriate driver without your intervention.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Perform the installation using VNC</term>
+ <listitem>
+ <para>
+ If the above options fail, you can use a separate system to access the graphical installation over the network, using the <firstterm>Virtual Network Computing</firstterm> (VNC) protocol. For details on installing using VNC, see <xref linkend="chap-vnc-installations" />.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Serial Console Not Detected</title>
+ <para>
+ In some cases, attempting to install in text mode using a serial console will result in no output on the console. This happens on systems which have a graphics card, but no monitor connected. If <application>Anaconda</application> detects a graphics card, it will attempt to use it for a display, even if no display is connected.
+ </para>
+ <para>
+ If you want to perform a text-based installation on a serial console, use the <option>inst.text</option> and <option>console=</option> boot options. See <xref linkend="chap-anaconda-boot-options" /> for more details.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="sect-troubleshooting-problems-during-installation">
+ <title>Trouble During the Installation</title>
+
+ <section id="sect-trouble-during-no-target">
+ <title>No Disks Detected</title>
+ <para>
+ In the <guilabel>Installation Destination</guilabel> screen, the following error message may appear at the bottom: <guilabel>No disks detected. Please shut down the computer, connect at least one disk, and restart to complete installation</guilabel>.
+ </para>
+ <para>
+ The message indicates that <application>Anaconda</application> did not find any writable storage devices to install to. In that case, first make sure that your system does have at least one storage device attached.
+ </para>
+ <para>
+ If your system uses a hardware RAID controller, verify that the controller is properly configured and working. See your controller's documentation for instructions.
+ </para>
+ <para>
+ If you are installing into one or more iSCSI devices and there is no local storage present on the system, make sure that all required LUNs (<firstterm>Logical Unit Numbers</firstterm>) are being presented to the appropriate HBA (<firstterm>Host Bus Adapter</firstterm>).
+ </para>
+ <para>
+ If you made sure you have a connected and properly configured storage device and the message still appears after you reboot the system and start the installation again, it means that the installation program failed to detect the storage. In most cases this message appears when you attempt to install on an SCSI device which has not been recognized by the installation program.
+ </para>
+ </section>
+
+ <!-- TODO <section id="sect-trouble-during-traceback">
+ <title>Reporting Traceback Messages</title>
+ <para>
+ If the graphical installation program encounters an error, it presents you with a crash reporting dialog box. You can then choose to send information about the problem you encountered to Red Hat. To send a crash report, you will need to enter your Customer Portal credentials. If you do not have a Customer Portal account, you can register at <ulink url="https://www.redhat.com/wapps/ugc/register.html" />. Automated crash reporting also requires a working network connection.
+ </para>
+ <figure>
+ <title>The Crash Reporting Dialog Box</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/crashreporting/crashreporting.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A message saying that an unknown error has occured.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ When the dialog appears, select <guibutton>Report Bug</guibutton> to report the problem, or <guibutton>Quit</guibutton> to exit the installation.
+ </para>
+ <para>
+ Optionally, click <guilabel>More Info</guilabel> to display detailed output that may help determine the cause of the error. If you are familiar with debugging, click <guibutton>Debug</guibutton>. This will take you to virtual terminal <systemitem>tty1</systemitem>, where you can request more precise information that will enhance the bug report. To return to the graphical interface from <systemitem>tty1</systemitem>, use the <command>continue</command> command.
+ </para>
+ <figure>
+ <title>The Expanded Crash Reporting Dialog Box</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/crashreporting/crashreporting_details.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ Details of the crash, showing the Python traceback
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ If you want to report the bug to the customer portal, follow the procedure below.
+ </para>
+ <procedure>
+ <title>Reporting Errors to Red Hat Customer Support</title>
+ <step>
+ <para>
+ In the menu that appears, select <guilabel>Report a bug to Red Hat Customer Portal</guilabel>.
+ </para>
+ </step>
+ <step>
+ <para>
+ To report the bug to Red Hat, you first need to provide your Customer Portal credentials. Click <guibutton>Configure Red Hat Customer Support</guibutton>.
+ </para>
+ <figure>
+ <title>Customer Portal Credentials</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/crashreporting/crashreporting_configure1.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A message saying that the Red Hat Customer Support is not properly configured, with a button you can click to configure your credentials.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </step>
+ <step>
+ <para>
+ A new window is now open, prompting you to enter your Customer Portal user name and password. Enter your Red Hat Customer Portal credentials.
+ </para>
+ <figure>
+ <title>Configure Red Hat Customer Support</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/crashreporting/crashreporting_configure2.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A dialog prompting you to enter your Customer Portal account details.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ If your network settings require you to use a <systemitem class="protocol">HTTP</systemitem> or <systemitem class="protocol">HTTPS</systemitem> proxy, you can configure it by expanding the <guilabel>Advanced</guilabel> menu and entering the address of the proxy server.
+ </para>
+ <para>
+ When you put in all required credentials, click <guilabel>OK</guilabel> to proceed.
+ </para>
+ </step>
+ <step>
+ <para>
+ A new window appears, containing a text field. Write down any useful information and comments here. Describe how the error can be reproduced by explaining each step you took before the crash reporting dialog appeared. Provide as much relevant detail as possible, including any information you acquired when debugging. Be aware that the information you provide here may become publicly visible on the Customer Portal.
+ </para>
+ <para>
+ If you do not know what caused the error, check the box labeled <guilabel>I don't know what caused this problem</guilabel> at the bottom of the dialog.
+ </para>
+ <para>
+ Then, click <guibutton>Forward</guibutton>.
+ </para>
+ <figure>
+ <title>Describe the Problem</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/crashreporting/crashreporting_describe.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A text input field, prompting you to describe the steps you took before you encountered the error you are reporting.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </step>
+ <step>
+ <para>
+ Next, review the information that will be sent to the Customer Portal. The explanation you provided is in the <guilabel>comment</guilabel> tab. Other tabs include such information as your system's host name and other details about the installation environment. You can remove any items you do not want sent to Red Hat, but be aware that providing less detail may affect the investigation of the issue.
+ </para>
+ <para>
+ Click <guibutton>Forward</guibutton> when you finish reviewing the information to be sent.
+ </para>
+ <figure>
+ <title>Review the Data to Be Sent</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/crashreporting/crashreporting_review.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A dialog window with several tabs, allowing you to review all information about your system that will be sent to the Customer Portal as part of the crash report.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </step>
+ <step>
+ <para>
+ Review the list of files that will be sent and included in the bug report as individual attachments. These files provide system information that will assist the investigation. If you do not wish to send certain files, uncheck the box next to each one. To provide additional files that may help fix the problem, click <guibutton>Attach a file</guibutton>.
+ </para>
+ <para>
+ Once you have reviewed the files to be sent, check the box labeled <guilabel>I have reviewed the data and agree with submitting it</guilabel>. Then, click <guibutton>Forward</guibutton> to send the report and attachments to the Customer Portal.
+ </para>
+ <figure>
+ <title>Review the Files to Be Sent</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/crashreporting/crashreporting_checkfiles.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>
+ A dialog window allowing you to review the files to be sent along with the report, unselect files you do not wish to send, and add additional files..
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </step>
+ <step>
+ <para>
+ When the dialog reports that processing has finished, you can click <guilabel>Show log</guilabel> to view details of the reporting process or <guilabel>Close</guilabel> to return to the initial crash reporting dialog box. There, click <guilabel>Quit</guilabel> to exit the installation.
+ </para>
+ </step>
+ </procedure>
+ </section>-->
+
+ </section>
+
+ <section id="sect-troubleshooting-problems-after-installation">
+ <title>Problems After Installation</title>
+
+ <section>
+ <title>Are You Unable to Boot With Your RAID Card?</title>
+ <para>
+ If you have performed an installation and cannot boot your system properly, you may need to reinstall and partition your system's storage differently.
+ </para>
+ <para>
+ Some BIOS types do not support booting from RAID cards. After you finish the installation and reboot the system for the first time, a text-based screen showing the boot loader prompt (for example, <prompt>grub></prompt>) and a flashing cursor may be all that appears. If this is the case, you must repartition your system and move your <filename>/boot</filename> partition and the boot loader outside the RAID array. The <filename>/boot</filename> partition and the boot loader must be on the same drive.
+ </para>
+ <para>
+ Once these changes have been made, you should be able to finish your installation and boot the system properly. For more information about partitioning, see <xref linkend="sect-installation-gui-storage-partitioning" />.
+ </para>
+ </section>
+
+ <section id="sect-trouble-after-graphical-boot">
+ <title>Trouble With the Graphical Boot Sequence</title>
+ <para>
+ After you finish the installation and reboot your system for the first time, it is possible that the system stops responding during the graphical boot sequence, requiring a reset. In this case, the boot loader is displayed successfully, but selecting any entry and attempting to boot the system results in a halt. This usually means a problem with the graphical boot sequence; to solve this issue, you must disable graphical boot. To do this, temporarily alter the setting at boot time before changing it permanently.
+ </para>
+ <procedure>
+ <title>Disabling Graphical Boot Temporarily</title>
+ <step>
+ <para>
+ Start your computer and wait until the boot loader menu appears. If you set your boot loader timeout period to 0, hold down the <keycap>Esc</keycap> key to access it.
+ </para>
+ </step>
+ <step>
+ <para>
+ When the boot loader menu appears, use your cursor keys to highlight the entry you want to boot and press the <keycap>e</keycap> key to edit this entry's options.
+ </para>
+ </step>
+ <step>
+ <para>
+ In the list of options, find the kernel line - that is, the line beginning with the keyword <literal>linux</literal> (or, in some cases, <literal>linux16</literal> or <literal>linuxefi</literal>). On this line, locate the <literal>rhgb</literal> option and delete it. The option may not be immediately visible; use the cursor keys to scroll up and down.
+ </para>
+ </step>
+ <step>
+ <para>
+ Press <keycap>F10</keycap> or <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo> to boot your system with the edited options.
+ </para>
+ </step>
+ </procedure>
+ <para>
+ If the system started successfully, you can log in normally. Then you will need to disable the graphical boot permanently - otherwise you will have to perform the previous procedure every time the system boots. To permanently change boot options, do the following.
+ </para>
+ <procedure>
+ <title>Disabling Graphical Boot Permanently</title>
+ <step>
+ <para>
+ Log in to the <systemitem>root</systemitem> account using the <command>su -</command> command:
+ </para>
+ <screen>
+<prompt>$</prompt> <command>su -</command>
+ </screen>
+ </step>
+ <step>
+ <para>
+ Open the <filename>/etc/default/grub</filename> configuration file using a plain text editor such as <application>vim</application>.
+ </para>
+ </step>
+ <step>
+ <para>
+ Within the <filename>grub</filename> file, locate the line beginning with <literal>GRUB_CMDLINE_LINUX</literal>. The line should look similar to the following:
+ </para>
+ <programlisting>
+GRUB_CMDLINE_LINUX="rd.lvm.lv=rhel/root rd.md=0 rd.dm=0 vconsole.keymap=us $([ -x /usr/sbin/rhcrashkernel-param ] && /usr/sbin/rhcrashkernel-param || :) rd.luks=0 vconsole.font=latarcyrheb-sun16 rd.lvm.lv=vg_rhel/swap rhgb quiet"
+ </programlisting>
+ <para>
+ On this line, delete the <literal>rhgb</literal> option.
+ </para>
+ </step>
+ <step>
+ <para>
+ Save the edited configuration file.
+ </para>
+ </step>
+ <step>
+ <para>
+ Refresh the boot loader configuration by executing the following command:
+ </para>
+ <screen>
+<prompt>#</prompt> <command>grub2-mkconfig --output=/boot/grub2/grub.cfg</command>
+ </screen>
+ </step>
+ </procedure>
+ <para>
+ After you finish this procedure, you can reboot your computer. Red Hat Enterprise Linux will not use the graphical boot sequence any more. If you wish to enable graphical boot, follow the same procedure, add the <literal>rhgb</literal> option to the <literal>GRUB_CMDLINE_LINUX</literal> line in the <filename>/etc/default/grub</filename> file and refresh the boot loader configuration again using the <command>grub2-mkconfig</command> command.
+ </para>
+ <para>
+ See the <citetitle>&PRODUCT; System Administrator's Guide</citetitle>, available at the <ulink url="http://docs.fedoraproject.org">Fedora Documentation website</ulink>, for more information about working with the <application>GRUB2</application> boot loader.
+ </para>
+ </section>
+
+ <section id="sect-trouble-after-graphical-login">
+ <title>Booting into a Graphical Environment</title>
+ <para>
+ If you have installed the <application>X Window System</application> and a desktop environment such as <application>GNOME</application>, but are not seeing a graphical desktop environment once you log into your system, you can start it manually using the <command>startx</command> command. Note, however, that this is just a one-time fix and does not change the log in process for future log ins.
+ </para>
+ <para>
+ To set up your system so that you can log in at a graphical login screen, you must change the default <application>systemd</application> target to <literal>graphical.target</literal>. When you are finished, reboot the computer. You will presented with a graphical login prompt after the system restarts.
+ </para>
+ <procedure>
+ <title>Setting Graphical Login as Default</title>
+ <step>
+ <para>
+ Open a shell prompt. If you are in your user account, become root by typing the <command>su -</command> command.
+ </para>
+ </step>
+ <step>
+ <para>
+ Change the default target to <systemitem>graphical.target</systemitem>. To do this, execute the following command:
+ </para>
+ <screen>
+<prompt>#</prompt> <command>systemctl set-default graphical.target</command>
+ </screen>
+ </step>
+ </procedure>
+ <para>
+ Graphical login is now enabled by default - you will be presented with a graphical login prompt after the next reboot. If you want to reverse this change and keep using the text-based login prompt, execute the following command as <systemitem>root</systemitem>:
+ </para>
+ <screen>
+<prompt>#</prompt> <command>systemctl set-default multi-user.target</command>
+ </screen>
+ <para>
+ For more information about targets in <application>systemd</application>, see the <citetitle>&PRODUCT; System Administrator's Guide</citetitle>, available at the <ulink url="http://docs.fedoraproject.org">Fedora Documentation website</ulink>.
+ </para>
+ </section>
+
+ <section id="sect-trouble-after-no-gui">
+ <title>No Graphical User Interface Present</title>
+ <para>
+ If you are having trouble getting <application>X</application> (the <application>X Window System</application>) to start, it is possible that it has not been installed. Some of the pre-set base environments you can select during the installation, such as <guilabel>Minimal install</guilabel> or <guilabel>Web Server</guilabel>, do not include a graphical interface - it has to be installed manually.
+ </para>
+ <para>
+ If you want <application>X</application>, you can install the necessary packages after the installation using the <application>Yum</application> package manager. For example, to install <application>GNOME</application>, use <command>yum install gnome-shell</command> as <systemitem class="username">root</systemitem>.
+ </para>
+ </section>
+
+ <section>
+ <title>X Server Crashing After User Logs In</title>
+ <para>
+ If you are having trouble with the <application>X</application> server crashing when a user logs in, one or more of your file systems may be full (or nearly full). To verify that this is the problem you are experiencing, execute the following command:
+ </para>
+ <screen>
+<prompt>$</prompt> <command>df -h</command>
+ </screen>
+ <para>
+ The output will help you diagnose which partition is full - in most cases, the problem will be on the <filename>/home</filename> partition. A sample output of the <command>df</command> command may look similar to the following:
+ </para>
+ <screen>
+Filesystem Size Used Avail Use% Mounted on
+/dev/mapper/vg_rhel-root 20G 6.0G 13G 32% /
+devtmpfs 1.8G 0 1.8G 0% /dev
+tmpfs 1.8G 2.7M 1.8G 1% /dev/shm
+tmpfs 1.8G 1012K 1.8G 1% /run
+tmpfs 1.8G 0 1.8G 0% /sys/fs/cgroup
+tmpfs 1.8G 2.6M 1.8G 1% /tmp
+/dev/sda1 976M 150M 760M 17% /boot
+/dev/dm-4 90G 90G 0 100% /home
+ </screen>
+ <para>
+ In the above example, you can see that the <filename>/home</filename> partition is full, which causes the crash. You can make some room on the partition by removing unneeded files. After you free up some disk space, start <application>X</application> using the <command>startx</command> command.
+ </para>
+ <para>
+ For additional information about <command>df</command> and an explanation of the options available (such as the <option>-h</option> option used in this example), see the <systemitem>df(1)</systemitem> man page.
+ </para>
+ </section>
+
+ <section id="sect-trouble-after-missing-ram">
+ <title>Is Your RAM Not Being Recognized?</title>
+ <para>
+ In some cases the kernel does not recognize all of your memory (RAM), which causes the system to use less memory than is installed. You can find out how much RAM is being utilized using the <command>free -m</command> command. If the displayed total amount of memory does not match your expectations, it is likely that at least one of your memory modules is faulty. On BIOS-based systems, you can use the <application>Memtest86+</application> utility to test your system's memory - see <xref linkend="sect-boot-options-memtest" /> for details.
+ </para>
+ <note>
+ <para>
+ Some hardware configurations have a part of the system's RAM reserved and unavailable to the main system. Notably, laptop computers with integrated graphics cards will reserve some memory for the GPU. For example, a laptop with 4 GB of RAM and an integrated Intel graphics card will show only roughly 3.7 GB of available memory.
+ </para>
+ <para>
+ Additionally, the <application>kdump</application> crash kernel dumping mechanism reserves some memory for the secondary kernel used in case of the primary kernel crashing. This reserved memory will also not be displayed as available when using the <command>free</command> command. For details about <application>kdump</application> and its memory requirements, see the <citetitle>&PRODUCT; System Administrator's Guide</citetitle>, available at the <ulink url="http://docs.fedoraproject.org">Fedora Documentation website</ulink>.
+ </para>
+ </note>
+ <para>
+ If you made sure that your memory does not have any issues, you can try and set the amount of memory manually using the <option>mem=</option> kernel option.
+ </para>
+ <procedure>
+ <title>Configuring the Memory Manually</title>
+ <step>
+ <para>
+ Start your computer and wait until the boot loader menu appears. If you set your boot loader timeout period to 0, hold down the <keycap>Esc</keycap> key to access it.
+ </para>
+ </step>
+ <step>
+ <para>
+ When the boot loader menu appears, use your cursor keys to highlight the entry you want to boot and press the <keycap>e</keycap> key to edit this entry's options.
+ </para>
+ </step>
+ <step>
+ <para>
+ In the list of options, find the kernel line - that is, the line beginning with the keyword <literal>linux</literal> (or, in some cases, <literal>linux16</literal>). Append the following option to the end of this line:
+ </para>
+ <screen>
+mem=<replaceable>xx</replaceable>M
+ </screen>
+ <para>
+ Replace <replaceable>xx</replaceable> with the amount of RAM you have in megabytes.
+ </para>
+ </step>
+ <step>
+ <para>
+ Press <keycap>F10</keycap> or <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo> to boot your system with the edited options.
+ </para>
+ </step>
+ <step>
+ <para>
+ Wait for the system to boot and log in. Then, open a command line and execute the <command>free -m</command> command again. If total amount of RAM displayed by the command matches your expectations, append the following to the line beginning with <literal>GRUB_CMDLINE_LINUX</literal> in the <filename>/etc/default/grub</filename> file to make the change permanent:
+ </para>
+ <screen>
+mem=<replaceable>xx</replaceable>M
+ </screen>
+ <para>
+ Replace <replaceable>xx</replaceable> with the amount of RAM you have in megabytes.
+ </para>
+ </step>
+ <step>
+ <para>
+ After you updated the file and saved it, refresh the boot loader configuration so that the change will take effect. Run the following command with root privileges:
+ </para>
+ <screen>
+<prompt>#</prompt> <command>grub2-mkconfig --output=/boot/grub2/grub.cfg</command>
+ </screen>
+ </step>
+ </procedure>
+ <para>
+ In <filename>/etc/default/grub</filename>, the above example would look similar to the following:
+ </para>
+ <programlisting>
+GRUB_TIMEOUT=5
+GRUB_DISTRIBUTOR="$(sed 's, release.*$,,g' /etc/system-release)"
+GRUB_DEFAULT=saved
+GRUB_DISABLE_SUBMENU=true
+GRUB_TERMINAL_OUTPUT="console"
+GRUB_CMDLINE_LINUX="rd.lvm.lv=rhel/root vconsole.font=latarcyrheb-sun16 rd.lvm.lv=rhel/swap $([ -x /usr/sbin/rhcrashkernel.param ] && /usr/sbin/rhcrashkernel-param || :) vconsole.keymap=us rhgb quiet mem=1024M"
+GRUB_DISABLE_RECOVERY="true"
+ </programlisting>
+ <para>
+ See the <citetitle>&PRODUCT; System Administrator's Guide</citetitle>, available at the <ulink url="http://docs.fedoraproject.org">Fedora Documentation website</ulink>, for more information about working with the <application>GRUB2</application> boot loader.
+ </para>
+ </section>
+
+ </section>
</chapter>
More information about the docs-commits
mailing list