Appendix F. Tools and tips for troubleshooting and bug reporting

The troubleshooting information in the following sections might be helpful when diagnosing issues at the start of the installation process. The following sections are for all supported architectures. However, if an issue is for a particular architecture, it is specified at the start of the section.

F.1. Dracut

Dracut is a tool that manages the initramfs image during the Linux operating system boot process. The dracut emergency shell is an interactive mode that can be initiated while the initramfs image is loaded. You can run basic troubleshooting commands from the dracut emergency shell. For more information, see the Troubleshooting section of the dracut man page.

F.2. Using installation log files

For debugging purposes, the installation program logs installation actions in files that are located in the /tmp directory. These log files are listed in the following table.

Table F.1. Log files generated during the installation

Log fileContents

/tmp/anaconda.log

General messages.

/tmp/program.log

All external programs run during the installation.

/tmp/storage.log

Extensive storage module information.

/tmp/packaging.log

yum and rpm package installation messages.

/tmp/dbus.log

Information about the dbus session that is used for installation program modules.

/tmp/sensitive-info.log

Configuration information that is not part of other logs and not copied to the installed system.

/tmp/syslog

Hardware-related system messages. This file contains messages from other Anaconda files.

If the installation fails, the messages are consolidated into /tmp/anaconda-tb-identifier, where identifier is a random string. After a successful installation, these files are copied to the installed system under the directory /var/log/anaconda/. However, if the installation is unsuccessful, or if the inst.nosave=all or inst.nosave=logs options are used when booting the installation system, these logs only exist in the installation program’s RAM disk. This means that the logs are not saved permanently and are lost when the system is powered down. To store them permanently, copy the files to another system on the network or copy them to a mounted storage device such as a USB flash drive.

F.2.1. Creating pre-installation log files

Use this procedure to set the inst.debug option to create log files before the installation process starts. These log files contain, for example, the current storage configuration.

Prerequisites

  • The Red Hat Enterprise Linux boot menu is open.

Procedure

  1. Select the Install Red Hat Enterprise Linux option from the boot menu.
  2. Press the Tab key on BIOS-based systems or the e key on UEFI-based systems to edit the selected boot options.
  3. Append inst.debug to the options. For example:

    vmlinuz ... inst.debug
  4. Press the Enter key on your keyboard. The system stores the pre-installation log files in the /tmp/pre-anaconda-logs/ directory before the installation program starts.
  5. To access the log files, switch to the console.
  6. Change to the /tmp/pre-anaconda-logs/ directory:

    # cd /tmp/pre-anaconda-logs/

F.2.2. Transferring installation log files to a USB drive

Use this procedure to transfer installation log files to a USB drive.

Prerequisites

  • You have backed up data from the USB drive.
  • You are logged into a root account and you have access to the installation program’s temporary file system.

Procedure

  1. Press Ctrl + Alt + F2 to access a shell prompt on the system you are installing.
  2. Connect a USB flash drive to the system and run the dmesg command:

    # dmesg

    A log detailing all recent events is displayed. At the end of this log, a set of messages is displayed. For example:

    [ 170.171135] sd 5:0:0:0: [sdb] Attached SCSI removable disk
  3. Note the name of the connected device. In the above example, it is sdb.
  4. Navigate to the /mnt directory and create a new directory that serves as the mount target for the USB drive. This example uses the name usb:

    # mkdir usb
  5. Mount the USB flash drive onto the newly created directory. In most cases, you do not want to mount the whole drive, but a partition on it. 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
  6. Verify that you mounted the correct device and partition by accessing it and listing its contents:

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

    # cp /tmp/*log /mnt/usb
  8. Unmount the USB flash drive. If you receive an error message that the target is busy, change your working directory to outside the mount (for example, /).

    # umount /mnt/usb

F.2.3. Transferring installation log files over the network

Use this procedure to transfer installation log files over the network.

Prerequisites

  • You are logged into a root account and you have access to the installation program’s temporary file system.

Procedure

  1. Press Ctrl + Alt + F2 to access a shell prompt on the system you are installing.
  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
    1. 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 where you want to save the log files. For example, if you want to log in as john on 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 is as follows:

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

      When connecting to the target system for the first time, the SSH client asks you to confirm that the fingerprint of the remote system is correct and that you want to continue:

      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)?
    2. Type yes and press Enter to continue. Provide a valid password when prompted. The files are transferred to the specified directory on the target system.

F.3. Detecting memory faults using the Memtest86 application

Faults in memory (RAM) modules can cause your system to fail unpredictably. In certain situations, memory faults might only cause errors with particular combinations of software. For this reason, you should test your system’s memory before you install Red Hat Enterprise Linux.

Note

Red Hat Enterprise Linux includes the Memtest86+ memory testing application for BIOS systems only. Support for UEFI systems is currently unavailable.

F.3.1. Running Memtest86

Use this procedure to run the Memtest86 application to test your system’s memory for faults before you install Red Hat Enterprise Linux.

Prerequisites

  • You have accessed the Red Hat Enterprise Linux boot menu.

Procedure

  1. From the Red Hat Enterprise Linux boot menu, select Troubleshooting > Run a memory test. The Memtest86 application window is displayed and testing begins immediately. By default, Memtest86 performs ten tests in every pass. After the first pass is complete, a message is displayed in the lower part of the window informing you of the current status. Another pass starts automatically.

    If Memtest86+ detects an error, the error is displayed in the central pane of the window and is highlighted in red. The message includes detailed information such as which test detected a problem, the memory location that is failing, and others. In most cases, a single successful pass of all 10 tests is sufficient to verify that your RAM is in good condition. In rare circumstances, however, errors that went undetected during the first pass might appear on subsequent passes. To perform a thorough test on important systems, run the tests overnight or for a few days to complete multiple passes.

    Note

    The amount of time it takes to complete a single full pass of Memtest86+ varies depending on your system’s configuration, notably the RAM size and speed. For example, on a system with 2 GiB of DDR2 memory at 667 MHz, a single pass takes 20 minutes to complete.

  2. Optional: Follow the on-screen instructions to access the Configuration window and specify a different configuration.
  3. To halt the tests and reboot your computer, press the Esc key at any time.

Additional resources

F.4. Verifying boot media

Verifying ISO images helps to avoid problems that are sometimes encountered during installation. These sources include DVD and ISO images stored on a disk or NFS server. Use this procedure to test the integrity of an ISO-based installation source before using it to install Red Hat Enterprise Linux.

Prerequisites

  • You have accessed the Red Hat Enterprise Linux boot menu.

Procedure

  1. From the boot menu, select Test this media & install Red Hat Enterprise Linux 8.1 to test the boot media.
  2. The boot process tests the media and highlights any issues.
  3. Optional: You can start the verification process by appending rd.live.check to the boot command line.

F.5. Consoles and logging during installation

The Red Hat Enterprise Linux installer uses the tmux terminal multiplexer to display and control several windows in addition to the main interface. Each of these windows serve a different purpose; they display several different logs, which can be used to troubleshoot issues during the installation process. One of the windows provides an interactive shell prompt with root privileges, unless this prompt was specifically disabled using a boot option or a Kickstart command.

Note

In general, there is no reason to leave the default graphical installation environment unless you need to diagnose an installation problem.

The terminal multiplexer is running in virtual console 1. To switch from the actual installation environment to tmux, press Ctrl+Alt+F1. To go back to the main installation interface which runs in virtual console 6, press Ctrl+Alt+F6.

Note

If you choose text mode installation, you will start in virtual console 1 (tmux), and switching to console 6 will open a shell prompt instead of a graphical interface.

The console running tmux has five available windows; their contents are described in the following table, along with keyboard shortcuts. Note that the keyboard shortcuts are two-part: first press Ctrl+b, then release both keys, and press the number key for the window you want to use.

You can also use Ctrl+b n, Alt+ Tab, and Ctrl+b p to switch to the next or previous tmux window, respectively.

Table F.2. Available tmux windows

ShortcutContents

Ctrl+b 1

Main installation program window. Contains text-based prompts (during text mode installation or if you use VNC direct mode), and also some debugging information.

Ctrl+b 2

Interactive shell prompt with root privileges.

Ctrl+b 3

Installation log; displays messages stored in /tmp/anaconda.log.

Ctrl+b 4

Storage log; displays messages related to storage devices and configuration, stored in /tmp/storage.log.

Ctrl+b 5

Program log; displays messages from utilities executed during the installation process, stored in /tmp/program.log.

F.6. Saving screenshots

You can press Shift+Print Screen at any time during the graphical installation to capture the current screen. The screenshots are saved to /tmp/anaconda-screenshots.

F.7. Display settings and device drivers

Some video cards have trouble booting into the Red Hat Enterprise Linux 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 fails, the installation program attempts to run in text mode.

There are several possible solutions to resolve display issues, most of which involve specifying custom boot options:

For more information, see Console boot options.

Table F.3. Solutions

SolutionDescription

Use the basic graphics mode

You can attempt to perform the installation using the basic graphics driver. To do this, either select Troubleshooting > Install Red Hat Enterprise Linux in basic graphics mode from the boot menu, or 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 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)*.

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 the Performing a remote RHEL installation using VNC section of the Performing an advanced RHEL 8 installation document.

*If specifying a custom video driver solves your problem, you should report it as a bug in Jira. The installation program should be able to detect your hardware automatically and use the appropriate driver without intervention.

F.8. Reporting error messages to Red Hat Customer Support

If the graphical installation encounters an error, it displays the unknown error dialog box. You can send information about the error to Red Hat Customer Support. To send a report, you must enter your Customer Portal credentials. If you do not have a Customer Portal account, you can register at https://www.redhat.com/wapps/ugc/register.html. Automated error reporting requires a network connection.

Prerequisite

The graphical installation program encountered an error and displayed the unknown error dialog box.

Procedure

  1. From the unknown error dialog box, click Report Bug to report the problem, or Quit to exit the installation.

    1. Optionally, click More Info…​ to display a detailed output that might help determine the cause of the error. If you are familiar with debugging, click Debug. This displays the virtual terminal tty1, where you can request additional information. To return to the graphical interface from tty1, use the continue command.
  2. Click Report a bug to Red Hat Customer Support.
  3. The Red Hat Customer Support - Reporting Configuration dialog box is displayed. From the Basic tab, enter your Customer Portal user name and password. If your network settings require you to use an HTTP or HTTPS proxy, you can configure it by selecting the Advanced tab and entering the address of the proxy server.
  4. Complete all fields and click OK.
  5. A text box is displayed. Explain each step that was taken before the unknown error dialog box was displayed.
  6. Select an option from the How reproducible is this problem drop-down menu and provide additional information in the text box.
  7. Click Forward.
  8. Verify that all the information you provided is in the Comment tab. The other tabs include information such as your system’s host name and other details about your installation environment. You can remove any of the information that you do not want to send to Red Hat, but be aware that providing less detail might affect the investigation of the issue.
  9. Click Forward when you have finished reviewing all tabs.
  10. A dialog box displays all the files that will be sent to Red Hat. Clear the check boxes beside the files that you do not want to send to Red Hat. To add a file, click Attach a file.
  11. Select the check box I have reviewed the data and agree with submitting it.
  12. Click Forward to send the report and attachments to Red Hat.
  13. Click Show log to view the details of the reporting process or click Close to return to the unknown error dialog box.
  14. Click Quit to exit the installation.