Appendix A. Troubleshooting

The following sections cover various troubleshooting information that might be helpful when diagnosing issues during different stages of the installation process.

A.1. Troubleshooting at the start of the installation process

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.

A.1.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.

A.1.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 A.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/ifcfg.log

Information about networking scripts.

/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.

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.

A.1.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 displayed.

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/

    Additional Resources

A.1.2.2. Transferring installation log files to a USB drive

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

Prerequisites

  • Back up any data on the USB drive before using this procedure.
  • 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

A.1.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.

A.1.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.

A.1.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

A.1.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 hard drive 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.

A.1.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 A.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.

A.1.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.

A.1.7. Resuming an interrupted download attempt

You can resume an interrupted download using the curl command.

Prerequisite

  • You have navigated to the Product Downloads section of the Red Hat Customer Portal at https://access.redhat.com/downloads, and selected the required variant, version, and architecture.
  • You have right-clicked on the required ISO file, and selected Copy Link Location to copy the URL of the ISO image file to your clipboard.

Procedure

  1. Download the ISO image from the new link. Add the --continue-at - option to automatically resume the download:

    $ curl --output directory-path/filename.iso 'new_copied_link_location' --continue-at -
  2. Use a checksum utility such as sha256sum to verify the integrity of the image file after the download finishes:

    $ sha256sum rhel-8.1-x86_64-dvd.iso
    			`85a...46c rhel-8.1-x86_64-dvd.iso`

    Compare the output with reference checksums provided on the Red Hat Enterprise Linux Product Download web page.

Example A.1. Resuming an interrupted download attempt

The following is an example of a curl command for a partially downloaded ISO image:

$ curl --output _rhel-8.1-x86_64-dvd.iso 'https://access.cdn.redhat.com//content/origin/files/sha256/85/85a...46c/rhel-8.1-x86_64-dvd.iso?_auth=141...963' --continue-at -

A.1.8. Cannot boot into the graphical installation

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 Section D.3, “Console boot options”.

Table A.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 8.1 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 installation document.

*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. The installation program should be able to detect your hardware automatically and use the appropriate driver without intervention.

A.2. Troubleshooting during the installation

The troubleshooting information in the following sections might be helpful when diagnosing issues during 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.

A.2.1. Disks are not detected

If the installation program cannot find a writable storage device to install to, it returns the following error message in the Installation Destination window: No disks detected. Please shut down the computer, connect at least one disk, and restart to complete installation.

Check the following items:

  • Your system has at least one storage device attached.
  • If your system uses a hardware RAID controller; verify that the controller is properly configured and working as expected. 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, verify that all required LUNs are presented to the appropriate Host Bus Adapter (HBA).

If the error message is still displayed after rebooting the system and starting the installation process, the installation program failed to detect the storage. In many cases the error message is a result of attempting to install on an iSCSI device that is not recognized by the installation program.

In this scenario, you must perform a driver update before starting the installation. Check your hardware vendor’s website to determine if a driver update is available. For more general information on driver updates, see the Updating drivers during installation section of the Performing an advanced RHEL installation document.

You can also consult the Red Hat Hardware Compatibility List, available at https://access.redhat.com/ecosystem/search/#/category/Server.

A.2.2. 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.

A.2.3. Partitioning issues for IBM Power Systems

Note

This issue is for IBM Power Systems.

If you manually created partitions, but cannot move forward in the installation process, you might not have created all the partitions that are necessary for the installation to proceed. At a minimum, you must have the following partitions:

  • / (root) partition
  • PReP boot partition
  • /boot partition (only if the root partition is an LVM logical volume)

See Section C.4, “Recommended partitioning scheme” for more information.

A.3. Troubleshooting after installation

The troubleshooting information in the following sections might be helpful when diagnosing issues after 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.

A.3.1. Cannot boot with a RAID card

If you cannot boot your system after the installation, you might need to reinstall and repartition your system’s storage. 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 displays the boot loader prompt (for example, grub>) and a flashing cursor might be displayed. If this is the case, you must repartition your system and move your /boot partition and the boot loader outside of 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.

A.3.2. Graphical boot sequence is not responding

When rebooting your system for the first time after installation, the system might be unresponsive during the graphical boot sequence. If this occurs, a reset is required. In this scenario, the boot loader menu is displayed successfully, but selecting any entry and attempting to boot the system results in a halt. This usually indicates that there is a problem with the graphical boot sequence. To resolve the issue, you must disable the graphical boot by temporarily altering the setting at boot time before changing it permanently.

Procedure: Disabling the graphical boot temporarily

  1. Start your system and wait until the boot loader menu is displayed. If you set your boot timeout period to 0, press the Esc key to access it.
  2. From the boot loader menu, use your cursor keys to highlight the entry you want to boot. Press the Tab key on BIOS-based systems or the e key on UEFI-based systems to edit the selected entry options.
  3. In the list of options, find the kernel line - that is, the line beginning with the keyword linux. On this line, locate and delete rhgb.
  4. Press F10 or Ctrl+X to boot your system with the edited options.

If the system started successfully, you can log in normally. However, if you do not disable graphical boot permanently, you must perform this procedure every time the system boots.

Procedure: Disabling the graphical boot permanently

  1. Log in to the root account on your system.
  2. Use the grubby tool to find the default GRUB2 kernel:

    # grubby --default-kernel
    /boot/vmlinuz-4.18.0-94.el8.x86_64
  3. Use the grubby tool to remove the rhgb boot option from the default kernel in your GRUB2 configuration. For example:

    # grubby --remove-args="rhgb" --update-kernel /boot/vmlinuz-4.18.0-94.el8.x86_64
  4. Reboot the system. The graphical boot sequence is no longer used. If you want to enable the graphical boot sequence, follow the same procedure, replacing the --remove-args="rhgb" parameter with the --args="rhgb" parameter. This restores the rhgb boot option to the default kernel in your GRUB2 configuration.

A.3.3. X server fails after log in

An X server is a program in the X Window System that runs on local machines, that is, the computers used directly by users. X server handles all access to the graphics cards, display screens and input devices, typically a keyboard and mouse on those computers. The X Window System, often referred to as X, is a complete, cross-platform and free client-server system for managing GUIs on single computers and on networks of computers. The client-server model is an architecture that divides the work between two separate but linked applications, referred to as clients and servers.*

If X server crashes after login, one or more of the file systems might be full. To troubleshoot the issue, execute the following command:

$ df -h

The output verifies which partition is full - in most cases, the problem is on the /home partition. The following is a sample output of the df command:

Filesystem                                  Size  Used Avail Use% Mounted on
devtmpfs                                    396M     0  396M   0%  /dev
tmpfs                                       411M     0  411M   0%  /dev/shm
tmpfs                                       411M  6.7M  405M   2%  /run
tmpfs                                       411M     0  411M   0%  /sys/fs/cgroup
/dev/mapper/rhel-root                       17G    4.1G  13G   25% /
/dev/sda1                                   1014M  173M 842M  17% /boot
tmpfs                                       83M    20K   83M   1%  /run/user/42
tmpfs                                       83M    84K  83M    1%  /run/user/1000
/dev/dm-4                                   90G    90G    0  100% /home

In the example, you can see that the /home partition is full, which causes the failure. Remove any unwanted 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.

*Source: http://www.linfo.org/x_server.html

A.3.4. RAM is not recognized

In some scenarios, the kernel does not recognize all 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 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.

Some hardware configurations have part of the system’s RAM reserved, and as a result, it is unavailable to the system. Some laptop computers with integrated graphics cards reserve a portion of memory for the GPU. For example, a laptop with 4 GiB of RAM and an integrated Intel graphics card shows roughly 3.7 GiB of available memory. Additionally, the kdump crash kernel dumping mechanism, which is enabled by default on most Red Hat Enterprise Linux systems, reserves some memory for the secondary kernel used in case of a primary kernel failure. This reserved memory is not displayed as available when using the free command.

Procedure: Manually configuring the memory

Use this procedure to manually set the amount of memory using the mem= kernel option.

  1. Start your system and wait until the boot loader menu is displayed. If you set your boot timeout period to 0, press the Esc key to access it.
  2. From the boot loader menu, use your cursor keys to highlight the entry you want to boot, and press the Tab key on BIOS-based systems or the e key on UEFI-based systems to edit the selected entry options.
  3. In the list of options, find the kernel line - that is, the line beginning with the keyword linux. Append the following option to the end of this line:

    mem=xxM
  4. Replace xx with the amount of RAM you have in MiB.
  5. Press F10 or Ctrl+X to boot your system with the edited options.
  6. Wait for the system to boot and then log in.
  7. Open a command line and execute the free -m command again. If the 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:

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

A.3.5. System is displaying signal 11 errors

A signal 11 error, commonly known as a segmentation fault means that a program accessed a memory location that it was not assigned. A signal 11 error can occur due to a bug in one of the software programs that are installed, or faulty hardware. If you receive a signal 11 error during the installation process, verify that you are using the most recent installation images and prompt the installation program to verify them to ensure they are not corrupt. For more information, see Section A.1.4, “Verifying boot media”.

Faulty installation media (such as an improperly burned or scratched optical disk) are a common cause of signal 11 errors. Verifying the integrity of the installation media is recommended before every installation. For information about obtaining the most recent installation media, see Section 2.6, “Downloading the installation ISO image”.

To perform a media check before the installation starts, append the rd.live.check boot option at the boot menu. If you performed a media check without any errors and you still have issues with segmentation faults, it usually indicates that your system encountered a hardware error. In this scenario, the problem is most likely in the system’s memory (RAM). This can be a problem even if you previously used a different operating system on the same computer without any errors.

Note

For AMD and Intel 64-bit and 64-bit ARM architectures: On BIOS-based systems, you can use the Memtest86+ memory testing module included on the installation media to perform a thorough test of your system’s memory. For more information, see Section A.1.3, “Detecting memory faults using the Memtest86 application”.

Other possible causes are beyond this document’s scope. Consult your hardware manufacturer’s documentation and also see the Red Hat Hardware Compatibility List, available online at https://access.redhat.com/ecosystem/search/#/category/Server.

A.3.6. Unable to IPL from network storage space

Note

This issue is for IBM Power Systems.

If you experience difficulties when trying to IPL from Network Storage Space (*NWSSTG), it is most likely due to a missing PReP partition. In this scenario, you must reinstall the system and create this partition during the partitioning phase or in the Kickstart file.

A.3.7. Using XDMCP

There are scenarios where you have installed the X Window System and want to log in to your Red Hat Enterprise Linux system using a graphical login manager. Use this procedure to enable the X Display Manager Control Protocol (XDMCP) and remotely log in to a desktop environment from any X-compatible client, such as a network-connected workstation or X11 terminal.

Note

XDMCP is not supported by the Wayland protocol. For more information, see the Using the desktop environment in RHEL 8 document.

Note

This issue is for IBM Z.

Procedure

  1. Open the /etc/gdm/custom.conf configuration file in a plain text editor such as vi or nano.
  2. In the custom.conf file, locate the section starting with [xdmcp]. In this section, add the following line:

    Enable=true
  3. Save the file and exit the text editor.
  4. Restart the X Window System. To do this, either reboot the system, or restart the GNOME Display Manager using the following command as root:

    # systemctl restart gdm.service
  5. Wait for the login prompt and log in using your user name and password. The X Window System is now configured for XDMCP. You can connect to it from another workstation (client) by starting a remote X session using the X command on the client workstation. For example:

    $ X :1 -query address
  6. Replace address with the host name of the remote X11 server. The command connects to the remote X11 server using XDMCP and displays the remote graphical login screen on display :1 of the X11 server system (usually accessible by pressing Ctrl-Alt-F8). You can also access remote desktop sessions using a nested X11 server, which opens the remote desktop as a window in your current X11 session. You can use Xnest to open a remote desktop nested in a local X11 session. For example, run Xnest using the following command, replacing address with the host name of the remote X11 server:

    $ Xnest :1 -query address

    For more information about XDMCP, see the X Window System documentation at http://www.x.org/releases/X11R7.6/doc/libXdmcp/xdmcp.html.

A.3.8. Using rescue mode

The installation program’s rescue mode is a minimal Linux environment that can be booted from the Red Hat Enterprise Linux DVD or other boot media. It contains command-line utilities for repairing a wide variety of issues. Rescue mode can be accessed from the Troubleshooting menu of the boot menu. In this mode, you can mount file systems as read-only, blacklist or add a driver provided on a driver disc, install or upgrade system packages, or manage partitions.

Note

The installation program’s rescue mode is different from rescue mode (an equivalent to single-user mode) and emergency mode, which are provided as parts of the systemd system and service manager.

To boot into rescue mode, you must be able to boot the system using one of the Red Hat Enterprise Linux boot media, such as a minimal boot disc or USB drive, or a full installation DVD.

Important

Advanced storage, such as iSCSI or zFCP devices, must be configured either using dracut boot options such as rd.zfcp= or root=iscsi: options, or in the CMS configuration file on IBM Z. It is not possible to configure these storage devices interactively after booting into rescue mode. For information about dracut boot options, see the dracut.cmdline(7) man page.

A.3.8.1. Booting into rescue mode

Use this procedure to boot into rescue mode.

Procedure

  1. Boot the system from either minimal boot media, or a full installation DVD or USB drive, and wait for the boot menu to be displayed.
  2. From the boot menu, either select Troubleshooting > Rescue a Red Hat Enterprise Linux system option, or append the inst.rescue option to the boot command line. To enter the boot command line, press the Tab key on BIOS-based systems or the e key on UEFI-based systems.
  3. Optional: If your system requires a third-party driver provided on a driver disc to boot, append the inst.dd=driver_name to the boot command line:

    inst.rescue inst.dd=driver_name
  4. Optional: If a driver that is part of the Red Hat Enterprise Linux distribution prevents the system from booting, append the modprobe.blacklist= option to the boot command line:

    inst.rescue modprobe.blacklist=driver_name
  5. Press Enter (BIOS-based systems) or Ctrl+X (UEFI-based systems) to boot the modified option. Wait until the following message is displayed:

    The rescue environment will now attempt to find your Linux installation and mount it under the directory: /mnt/sysimage/. You can then make any changes required to your system. Choose 1 to proceed with this step. You can choose to mount your file systems read-only instead of read-write by choosing 2. If for some reason this process does not work choose 3 to skip directly to a shell.
    
    1) Continue
    2) Read-only mount
    3) Skip to shell
    4) Quit (Reboot)

    If you select 1, the installation program attempts to mount your file system under the directory /mnt/sysimage/. You are notified if it fails to mount a partition. If you select 2, it attempts to mount your file system under the directory /mnt/sysimage/, but in read-only mode. If you select 3, your file system is not mounted.

  6. Select 1 to continue. Once your system is in rescue mode, a prompt appears on VC (virtual console) 1 and VC 2. Use the Ctrl+Alt+F1 key combination to access VC 1 and Ctrl+Alt+F2 to access VC 2:

    sh-4.2#
  7. Even if your file system is mounted, the default root partition while in rescue mode is a temporary root partition, not the root partition of the file system used during normal user mode (multi-user.target or graphical.target). If you selected to mount your file system and it mounted successfully, you can change the root partition of the rescue mode environment to the root partition of your file system by executing the following command:

    sh-4.2# chroot /mnt/sysimage

    This is useful if you need to run commands, such as rpm, that require your root partition to be mounted as /. To exit the chroot environment, type exit to return to the prompt.

  8. If you selected 3, you can still try to mount a partition or LVM2 logical volume manually inside rescue mode by creating a directory, such as /directory/, and typing the following command:

    sh-4.2# mount -t xfs /dev/mapper/VolGroup00-LogVol02 /directory

    In the above command, /directory/ is the directory that you created and /dev/mapper/VolGroup00-LogVol02 is the LVM2 logical volume you want to mount. If the partition is a different type than XFS, replace the xfs string with the correct type (such as ext4).

  9. If you do not know the names of all physical partitions, use the following command to list them:

    sh-4.2# fdisk -l

    If you do not know the names of all LVM2 physical volumes, volume groups, or logical volumes, use the pvdisplay, vgdisplay or lvdisplay commands.

A.3.8.2. Using an SOS report in rescue mode

The sosreport command-line utility collects configuration and diagnostic information, such as the running kernel version, loaded modules, and system and service configuration files from the system. The utility output is stored in a tar archive in the /var/tmp/ directory. The sosreport utility is useful for analyzing system errors and troubleshooting. Use this procedure to capture an sosreport output in rescue mode.

Prerequisites

  • You have booted into rescue mode.
  • You have mounted the installed system / (root) partition in read-write mode.
  • You have contacted Red Hat Support about your case and received a case number.

Procedure

  1. Change the root directory to the /mnt/sysimage/ directory:

    sh-4.2# chroot /mnt/sysimage/
  2. Execute sosreport to generate an archive with system configuration and diagnostic information:

    sh-4.2# sosreport
    Important

    sosreport prompts you to enter your name and the case number you received from Red Hat Support. Use only letters and numbers because adding any of the following characters or spaces could render the report unusable:

    # % & { } \ < > > * ? / $ ~ ' " : @ + ` | =

  3. Optional: If you want to transfer the generated archive to a new location using the network, it is necessary to have a network interface configured. In this scenario, use the dynamic IP addressing as no other steps required. However, when using static addressing, enter the following command to assign an IP address (for example 10.13.153.64/23) to a network interface, for example dev eth0:

    bash-4.2# ip addr add 10.13.153.64/23 dev eth0
  4. Exit the chroot environment:

    sh-4.2# exit
  5. Store the generated archive in a new location, from where it can be easily accessible:

    sh-4.2# cp /mnt/sysimage/var/tmp/sosreport new_location
  6. For transferring the archive through the network, use the scp utility:

    sh-4.2# scp /mnt/sysimage/var/tmp/sosreport username@hostname:sosreport

    Additional resources

A.3.8.3. Reinstalling the GRUB2 boot loader

In some scenarios, the GRUB2 boot loader is mistakenly deleted, corrupted, or replaced by other operating systems. Use this procedure to reinstall GRUB2 on the master boot record.

Prerequisites

  • You have booted into rescue mode.
  • You have mounted the installed system / (root) partition in read-write mode.

Procedure

  1. Change the root partition:

    sh-4.2# chroot /mnt/sysimage/
  2. Reinstall the GRUB2 boot loader, where install_device is the boot device, typically, /dev/sda:

    sh-4.2# /sbin/grub2-install install_device
  3. Reboot the system.

A.3.8.4. Using RPM to add or remove a driver

Missing or malfunctioning drivers cause problems when booting the system. Rescue mode provides an environment in which you can add or remove a driver even when the system fails to boot. Wherever possible, it is recommended that you use the RPM package manager to remove malfunctioning drivers or to add updated or missing drivers. Use the following procedures to add or remove a driver.

Important

When you install a driver from a driver disc, the driver disc updates all initramfs images on the system to use this driver. If a problem with a driver prevents a system from booting, you cannot rely on booting the system from another initramfs image.

Procedure: Adding a driver using RPM

Use this procedure to add a driver.

Prerequisites

  • You have booted into rescue mode.
  • You have mounted the installed system in read-write mode.

    1. Make the RPM package that contains the driver available. For example, mount a CD or USB flash drive and copy the RPM package to a location of your choice under /mnt/sysimage/, for example: /mnt/sysimage/root/drivers/.
    2. Change the root directory to /mnt/sysimage/:

      sh-4.2# chroot /mnt/sysimage/
    3. Use the rpm -ivh command to install the driver package. For example, run the following command to install the xorg-x11-drv-wacom driver package from /root/drivers/:

      sh-4.2# rpm -­ivh /root/drivers/xorg-x11-drv-wacom-0.23.0-6.el7.x86_64.rpm
      Note

      The /root/drivers/ directory in this chroot environment is the /mnt/sysimage/root/drivers/ directory in the original rescue environment.

    4. Exit the chroot environment:

      sh-4.2# exit

Procedure: Removing a driver using RPM

Use this procedure to remove a driver.

Prerequisites

  • You have booted into rescue mode.
  • You have mounted the installed system in read-write mode.

    1. Change the root directory to the /mnt/sysimage/ directory:

      sh-4.2# chroot /mnt/sysimage/
    2. Use the rpm -e command to remove the driver package. For example, to remove the xorg-x11-drv-wacom driver package, run:

      sh-4.2# rpm -e xorg-x11-drv-wacom
    3. Exit the chroot environment:

      sh-4.2# exit

      If you cannot remove a malfunctioning driver for some reason, you can instead blacklist the driver so that it does not load at boot time.

    4. When you have finished adding and removing drivers, reboot the system.

A.3.9. ip= boot option returns an error

Using the ip= boot option format ip=[ip address] for example, ip=192.168.1.1 returns the error message Fatal for argument 'ip=[insert ip here]'\n sorry, unknown value [ip address] refusing to continue.

In previous releases of Red Hat Enterprise Linux, the boot option format was:

--ip=192.168.1.15 --netmask=255.255.255.0 --gateway=192.168.1.254 --nameserver=192.168.1.250 --hostname=myhost1

However, in Red Hat Enterprise Linux 8, the boot option format is:

ip=192.168.1.15::192.168.1.254:255.255.255.0:myhost1::none: nameserver=192.168.1.250

To resolve the issue, use the format: ip=ip::gateway:netmask:hostname:interface:none where:

  • ip specifies the client ip address. You can specify IPv6 addresses in square brackets, for example, [2001:DB8::1].
  • gateway is the default gateway. IPv6 addresses are also accepted.
  • netmask is the netmask to be used. This can be either a full netmask, for example, 255.255.255.0, or a prefix, for example, 64.
  • hostname is the host name of the client system. This parameter is optional.

For more information, see Section D.2, “Network boot options”.