Troubleshooting

This chapter offers some pointers on how to get help when something goes wrong. It also discusses some common installation problems and their solutions.

Getting Help

There are many places on the internet which can help you when you encounter a problem not described in this chapter: discussion boards, blogs, IRC, and more. Some of the more popular places where you can find help include:

  • Ask Fedora - Fedora’s knowledge base, available in multiple languages

  • The #fedora IRC channel on FreeNode - one of the main IRC channels used by Fedora users, English only

  • Fedora Project Wiki - the official wiki for Fedora Project

  • Stack Exchange - an English language Q&A board, not specific to Fedora

The above list is by no means complete - you can find help in many other places as well. Additional information about available resources such as IRC channels and mailing lists is available at https://fedoraproject.org/wiki/Communicating_and_getting_help.

Before you open a new discussion or ask anyone for help on IRC, you should always do some research on your own. If you are encountering an issue, there is usually a good chance that someone else ran into the same problem before you and published a solution somewhere. Opening a discussion about something already explained elsewhere, or asking a common question which has been answered many times before, is not likely to result in a friendly, constructive response.

When you ask for help troubleshooting problems related to the installation, you may be asked to provide log files generated by the installer. The sections below explain which files are generated, what their contents are, and how to transfer them from the installation system.

Log Files Generated During the Installation

For debugging purposes, Anaconda logs installation actions into files in the /tmp directory. These files are listed in the following table.

Table 1. Log Files and Their Contents
Log file Contents

/tmp/anaconda.log

general Anaconda messages

/tmp/program.log

all external programs run during the installation

/tmp/storage.log

extensive storage module information

/tmp/packaging.log

dnf and rpm package installation messages

/tmp/syslog

hardware-related system messages

If the installation fails, the messages from these files are consolidated into /tmp/anaconda-tb-identifier, where identifier is a random string.

Transferring Log Files from the Installation System

All of the files described in Log Files Generated During the Installation 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 scp 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.

Transferring Log Files Onto a USB Drive
  1. On the system you are installing, press Ctrl+Alt+F2 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.

  2. Connect a USB flash drive to the system and execute the dmesg 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:

    [  170.171135] sd 5:0:0:0: [sdb] Attached SCSI removable disk

    Note the name of the connected device - in the above example, it is sdb.

  3. Go to the /mnt 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 usb.

    # mkdir usb
  4. 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 sdb - use the name of the partition you want to write the log files to. In this example, the name sdb1 is used.

    # mount /dev/sdb1 /mnt/usb

    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.

    # cd /mnt/usb
    # ls
  5. Copy the log files to the mounted device.

    # cp /tmp/*log /mnt/usb
  6. 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, /).

    # umount /mnt/usb

The log files from the installation are now saved on the USB flash drive.

Transferring Log Files Over the Network
  1. On the system you are installing, press Ctrl+Alt+F2 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.

  2. Switch to the /tmp directory where the log files are located:

    # cd /tmp
  3. Copy the log files onto another system on the network using the scp command:

    # scp *log user@address:path

    Replace user with a valid user name on the target system, address with the target system’s address or host name, and path with the path to the directory you wish to save the log files into. For example, if you want to log in as john to a system with an IP address of 192.168.0.122 and place the log files into the /home/john/logs/ directory on that system, the command will have the following form:

    # scp *log john@192.168.0.122:/home/john/logs/

    When connecting to the target system for the first time, you may encounter a message similar to the following:

    The authenticity of host '192.168.0.122 (192.168.0.122)' can't be established.
    ECDSA key fingerprint is a4:60:76:eb:b2:d0:aa:23:af:3d:59:5c:de:bb:c4:42.
    Are you sure you want to continue connecting (yes/no)?

    Type yes and press Enter 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.

Trouble Beginning the Installation

Problems with Booting into the Graphical Installation

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.

There are several possible solutions to display issues, most of which involve specifying custom boot options. For more information, see Configuring the Installation System at the Boot Menu.

Use the basic graphics mode

You can attempt to perform the installation using the basic graphics driver. To do this, edit the installation program’s boot options and append inst.xdriver=vesa at the end of the command line.

Specify the display resolution manually

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 inst.resolution=x option at the boot menu, where x is your display’s resolution (for example, 1024x768).

Use an alternate video driver

You can also attempt to specify a custom video driver, overriding the installation program’s automatic detection. To specify a driver, use the inst.xdriver=x option, where x is the device driver you want to use (for example, nouveau).

If specifying a custom video driver solves your problem, you should report it as a bug at https://bugzilla.redhat.com under the anaconda component. Anaconda should be able to detect your hardware automatically and use the appropriate driver without your intervention.

Perform the installation using VNC

If the above options fail, you can use a separate system to access the graphical installation over the network, using the Virtual Network Computing (VNC) protocol. For details on installing using VNC, see Installing Using VNC.

Serial Console Not Detected

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 Anaconda detects a graphics card, it will attempt to use it for a display, even if no display is connected.

If you want to perform a text-based installation on a serial console, use the inst.text and console= boot options. See Boot Options for more details.

Trouble During the Installation

No Disks Detected

In the Installation Destination screen, the following error message may appear at the bottom: No disks detected. Please shut down the computer, connect at least one disk, and restart to complete installation.

The message indicates that Anaconda 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.

If your system uses a hardware RAID controller, verify that the controller is properly configured and working. See your controller’s documentation for instructions.

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 (Logical Unit Numbers) are being presented to the appropriate HBA (Host Bus Adapter).

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.

Problems After Installation

Resetting the Root Password

If you lost the root password to the system and you have access to the boot loader, you can reset the password by editing the GRUB2 configuration.

Resetting the Root Password
  1. Boot your system and wait until the GRUB2 menu appears.

  2. In the boot loader menu, highlight any entry and press e to edit it.

  3. Find the line beginning with linux. At the end of this line, append the following:

    init=/bin/sh
  4. Press F10 or Ctrl+X to boot the system using the options you just edited.

    Once the system boots, you will be presented with a shell prompt without having to enter any user name or password:

    sh-4.2#
  5. Load the installed SELinux policy:

    sh-4.2# /usr/sbin/load_policy -i
  6. Execute the following command to remount your root partition:

    sh4.2# mount -o remount,rw /
  7. Reset the root password:

    sh4.2# passwd root

    When prompted to, enter your new root password and confirm by pressing the Enter key. Enter the password for the second time to make sure you typed it correctly and confirm with Enter again. If both passwords match, a message informing you of a successful root password change will appear.

  8. Remount the root partition again, this time as read-only:

    sh4.2# mount -o remount,ro /
  9. Reboot the system. From now on, you will be able to log in as the root user using the new password set up during this procedure.

Are You Unable to Boot With Your RAID Card?

If you have performed an installation and cannot boot your system properly, you may need to reinstall and partition your system’s storage differently.

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, grub>) and a flashing cursor may be all that appears. If this is the case, you must repartition your system and move your /boot partition and the boot loader outside the RAID array. The /boot partition and the boot loader must be on the same drive.

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 Installation Destination.

Trouble With the Graphical Boot Sequence

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.

Disabling Graphical Boot Temporarily
  1. Start your computer and wait until the boot loader menu appears. If you set your boot loader timeout period to 0, hold down the Esc key to access it.

  2. When the boot loader menu appears, use your cursor keys to highlight the entry you want to boot and press the e key to edit this entry’s options.

  3. In the list of options, find the kernel line - that is, the line beginning with the keyword linux (or, in some cases, linux16 or linuxefi). On this line, locate the rhgb option and delete it. The option may not be immediately visible; use the cursor keys to scroll up and down.

  4. Press F10 or Ctrl+X to boot your system with the edited options.

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.

Disabling Graphical Boot Permanently
  1. Log in to the root account using the su - command:

    $ su -
  2. Open the /etc/default/grub configuration file using a plain text editor such as vim.

  3. Within the grub file, locate the line beginning with GRUB_CMDLINE_LINUX. The line should look similar to the following:

    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"

    On this line, delete the rhgb option.

  4. Save the edited configuration file.

  5. Refresh the boot loader configuration by executing the following command:

    # grub2-mkconfig --output=/boot/grub2/grub.cfg

After you finish this procedure, you can reboot your computer. Fedora will not use the graphical boot sequence any more. If you wish to enable graphical boot, follow the same procedure, add the rhgb option to the GRUB_CMDLINE_LINUX line in the /etc/default/grub file and refresh the boot loader configuration again using the grub2-mkconfig command.

See the Fedora System Administrator’s Guide, available at http://docs.fedoraproject.org/, for more information about working with the GRUB2 boot loader.

Booting into a Graphical Environment

If you have installed the X Window System and a desktop environment such as GNOME, but are not seeing a graphical desktop environment once you log into your system, you can start it manually using the startx command. Note, however, that this is just a one-time fix and does not change the log in process for future log ins.

To set up your system so that you can log in at a graphical login screen, you must change the default systemd target to graphical.target. When you are finished, reboot the computer. You will presented with a graphical login prompt after the system restarts.

Setting Graphical Login as Default
  1. Open a shell prompt. If you are in your user account, become root by typing the su - command.

  2. Change the default target to graphical.target. To do this, execute the following command:

    # systemctl set-default graphical.target

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

# systemctl set-default multi-user.target

For more information about targets in systemd, see the Fedora System Administrator’s Guide, available at http://docs.fedoraproject.org/.

No Graphical User Interface Present

If you are having trouble getting X (the X Window System) 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 Minimal install or Web Server, do not include a graphical interface - it has to be installed manually.

If you want X, you can install the necessary packages after the installation using the DNF package manager. For example, to install GNOME, use dnf install gnome-shell as root.

X Server Crashing After User Logs In

If you are having trouble with the X 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:

$ df -h

The output will help you diagnose which partition is full - in most cases, the problem will be on the /home partition. A sample output of the df command may look similar to the following:

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

In the above example, you can see that the /home 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 X using the startx command.

For additional information about df and an explanation of the options available (such as the -h option used in this example), see the df(1) man page.

Is Your RAM Not Being Recognized?

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 free -m 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 Memtest86+ utility to test your system’s memory - see Loading the Memory (RAM) Testing Mode for details.

If you have 4GB or more memory installed, but Fedora only shows around 3.5GB or 3.7GB, you have probably installed a 32-bit version of Fedora on a 64bit kernel. For modern systems, use the 64-bit (x86_64) version.

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, even with a 64-bit system.

Additionally, the kdump 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 free command. For details about kdump and its memory requirements, see the Fedora System Administrator’s Guide, available at http://docs.fedoraproject.org/.

If you made sure that your memory does not have any issues, you can try and set the amount of memory manually using the mem= kernel option.

Configuring the Memory Manually
  1. Start your computer and wait until the boot loader menu appears. If you set your boot loader timeout period to 0, hold down the Esc key to access it.

  2. When the boot loader menu appears, use your cursor keys to highlight the entry you want to boot and press the e key to edit this entry’s options.

  3. In the list of options, find the kernel line - that is, the line beginning with the keyword linux (or, in some cases, linux16). Append the following option to the end of this line:

    mem=xxM

    Replace xx with the amount of RAM you have in megabytes.

  4. Press F10 or Ctrl+X to boot your system with the edited options.

  5. Wait for the system to boot and log in. Then, open a command line and execute the free -m command again. If total amount of RAM displayed by the command matches your expectations, append the following to the line beginning with GRUB_CMDLINE_LINUX in the /etc/default/grub file to make the change permanent:

    mem=xxM

    Replace xx with the amount of RAM you have in megabytes.

  6. 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:

    # grub2-mkconfig --output=/boot/grub2/grub.cfg

In /etc/default/grub, the above example would look similar to the following:

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"

See the Fedora System Administrator’s Guide, available at http://docs.fedoraproject.org/, for more information about working with the GRUB2 boot loader.