DocsICP FilingConsole
Documentation

Fix an invalid GRUB configuration on a Linux instance

Updated at:
Copy as MD
Product
My Favorites

Repair an invalid GRUB configuration that prevents a Linux ECS instance from starting.

Prerequisites

The instance health diagnostics tool detected an invalid GRUB configuration on the instance.

Background

Problem description: A Linux instance fails to start due to an invalid GRUB configuration.

Cause: The GRUB configuration contains a root file system parameter. If this parameter does not point to the correct partition on the system disk, such as /dev/vda1, or if the UUID does not match the root file system, the kernel cannot load the root file system and the instance fails to start.

Prerequisites

These solutions apply only to Linux systems in legacy boot mode, not UEFI. Verify the boot mode before you proceed.

  1. Find a Linux instance with the same instance type.

    If no such instance exists, create one using the wizard.

  2. Log on to the instance. See Connect to an instance using a VNC connection.

  3. Verify the boot mode.

    Check the firmware directory:

    ls /sys/firmware/

    Sample output:

    acpi  dmi  memmap  qemu_fw_cfg

Fix the GRUB configuration using a repair disk

Note

This solution applies only to Linux systems in legacy boot mode, not UEFI.

  1. Connect to the problematic instance remotely.
    When a repair disk is attached to an ECS instance, you can connect to the instance only using a VNC connection. For more information, see Connect to an instance using VNC.
  2. View the mount information of the original system disk of the problematic instance.
    On the repair disk, the file system of the original system disk is mounted on a temporary directory. You can find the information about the temporary directory in one of the following ways:
    • In the Mounted Instance section on the system disk details page, the temporary directory uses the format /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse****, where bp19bspzms79kqse**** is the serial number of the original system disk of the instance.
    • On the repair disk, run the mount command to view the information. For example, if the device path of the original system disk is /dev/vda, the command is:
      mount | grep /dev/vda
      The following output is returned:
      /dev/vda1 on /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse**** type ext4 (rw,relatime)

  3. Mount virtual file systems (/dev, /proc, /sys) to the chroot environment so that grub2-mkconfig can detect the root partition.

    Sample commands:

    mount --bind /dev /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse****/dev
mount --bind /proc /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse****/proc
mount --bind /sys /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse****/sys
  4. Run the chroot command to switch the root directory to the temporary path of the original system disk and enter the chroot environment.
    You must repair the files in the temporary path of the original system disk. For example, if the temporary path is /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse****, the command is:
    chroot /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse****

  5. Back up the GRUB configuration file.

    Back up /boot/grub2/grub.cfg to /root/grub.cfg for rollback if needed.

    cp /boot/grub2/grub.cfg /root/grub.cfg

  6. Regenerate the GRUB configuration file.

    Detect the root file system UUID and write it to the GRUB configuration file:

    grub2-mkconfig -o /boot/grub2/grub.cfg

  7. Verify the root file system parameter in the GRUB configuration file.

    Sample command:

    grep -n -E "(kernel|linux[16]*[efi]*)[[:space:]]+(/boot)?/vmlinuz-.*root=" /boot/grub2/grub.cfg /boot/grub2/grubenv

    Sample output:

    /boot/grub2/grub.cfg:99:     linux16 /boot/vmlinuz-3.10.0-514.26.2.el7.x86_64 root=UUID=48609326-10e3-40c2-93b3-3f0d9798**** ro crashkernel=auto   net.ifnames=0  console=tty0 console=ttyS0,115200n8
/boot/grub2/grub.cfg:114:    linux16 /boot/vmlinuz-3.10.0-327.el7.x86_64 root=UUID=48609326-10e3-40c2-93b3-3f0d9798**** ro crashkernel=auto   net.ifnames=0  console=tty0 console=ttyS0,115200n8
/boot/grub2/grub.cfg:128:    linux16 /boot/vmlinuz-0-rescue-36dc953195bb4389870d2591ff6bfea5 root=UUID=48609326-10e3-40c2-93b3-3f0d9798**** ro crashkernel=auto   net.ifnames=0  console=tty0 console=ttyS0,115200n8

  8. Exit the repair environment and verify the instance status.

    1. Exit the chroot environment.

    2. Unmount the virtual file systems.

      Sample commands:

      umount /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse****/dev
umount /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse****/proc
umount /tmp/ecs-offline-diagnose_disk-bp19bspzms79kqse****/sys

    3. On the Offline Diagnosis page in the ECS console, detach the repair disk.

    4. Connect to the repaired instance and verify that it works.

Fix the GRUB configuration using an intermediate instance

Detach the system disk from the problematic instance, attach it to an intermediate instance (another Linux instance in the same region), and fix the GRUB configuration.

  1. Detach the system disk from the problematic instance and attach it as a data disk to the intermediate instance. See Steps 1 to 3 in How to log on to a problematic system disk by attaching it as a data disk to an ECS instance.

    Note

    Stop at the mount /dev/vdb1 /mnt step. Do not run chroot /mnt. If you already ran chroot /mnt, run exit first.

  2. Mount virtual file systems (/dev, /proc, /sys) to the chroot environment so that grub2-mkconfig can detect the root partition.

    Sample commands:

    mount --bind /dev /mnt/dev
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys

  3. Switch to the chroot environment.

    chroot /mnt

    The /dev, /proc, and /sys directories should now contain the same mappings as on a normal instance.

  4. Back up the GRUB configuration file.

    Back up /boot/grub2/grub.cfg to /root/grub.cfg for rollback if needed.

    cp /boot/grub2/grub.cfg /root/grub.cfg

  5. Regenerate the GRUB configuration file.

    Detect the root file system UUID and write it to the GRUB configuration file:

    grub2-mkconfig -o /boot/grub2/grub.cfg

  6. Verify the root file system parameter in the GRUB configuration file.

    Sample command:

    grep -n -E "(kernel|linux[16]*[efi]*)[[:space:]]+(/boot)?/vmlinuz-.*root=" /boot/grub2/grub.cfg /boot/grub2/grubenv

    Sample output:

    /boot/grub2/grub.cfg:99:     linux16 /boot/vmlinuz-3.10.0-514.26.2.el7.x86_64 root=UUID=48609326-10e3-40c2-93b3-3f0d9798**** ro crashkernel=auto   net.ifnames=0  console=tty0 console=ttyS0,115200n8
/boot/grub2/grub.cfg:114:    linux16 /boot/vmlinuz-3.10.0-327.el7.x86_64 root=UUID=48609326-10e3-40c2-93b3-3f0d9798**** ro crashkernel=auto   net.ifnames=0  console=tty0 console=ttyS0,115200n8
/boot/grub2/grub.cfg:128:    linux16 /boot/vmlinuz-0-rescue-36dc953195bb4389870d2591ff6bfea5 root=UUID=48609326-10e3-40c2-93b3-3f0d9798**** ro crashkernel=auto   net.ifnames=0  console=tty0 console=ttyS0,115200n8

  7. Exit the repair environment and verify the instance status.

    1. Exit the chroot environment.

    2. Unmount the virtual file systems.

      Sample commands:

      umount /mnt/dev
umount /mnt/proc
umount /mnt/sys

    3. Unmount the system disk.

      Sample command:

      umount /mnt

    4. Reattach the system disk to the original instance. See Step 5 in How to log on to a problematic system disk by attaching it as a data disk to an ECS instance.

    5. Connect to the repaired instance and verify that it works.