virt-rescue

virt-rescue is a command-line tool used in virtualized environments to rescue a virtual machine (VM) from boot problems or to troubleshoot system issues. It provides a minimal, live environment where you can mount and repair the filesystem of a VM that is having trouble booting.

The tool is typically used in conjunction with libvirt and hypervisors like KVM, QEMU, or Xen. It allows system administrators to troubleshoot and fix a VM's disk or boot problems without needing to boot the VM itself.

Purpose of virt-rescue

The primary purpose of virt-rescue is to provide a recovery environment for a virtual machine in a non-bootable state. When a VM cannot boot due to disk corruption, misconfiguration, or other issues, virt-rescue allows the administrator to:

  • Mount the VM's virtual disk.

  • Access the VM's filesystem and fix errors or restore configurations.

  • Modify boot configurations or perform file system repairs.

  • Access logs and troubleshoot issues preventing the VM from booting.

How virt-rescue Works

virt-rescue starts a minimal Linux environment and mounts the virtual disks of the VM. You can then use typical Linux system recovery tools (like fsck, mount, chroot, etc.) to diagnose and repair the system.

Basic Syntax

virt-rescue [options] [domain]
  • domain: The name or ID of the virtual machine that you want to rescue.

Common Options

  • -a, --autorescue: Automatically attempt to mount the VM's disks and provide rescue tools.

  • --no-mount: Prevents virt-rescue from automatically mounting the disks. Useful if you want to manually mount them later.

  • -v, --verbose: Provides more detailed output, including logs of the rescue process.

  • -d, --domain: Specify the domain (VM) name or ID to enter the rescue environment.

  • -h, --help: Shows help and available options.

Example Usage

  1. Start Rescue Environment for a Specific VM:

    To start a rescue session for a virtual machine named vm1, run:

    virt-rescue vm1

    This command will create a minimal rescue environment and mount the disks of vm1 automatically, allowing you to troubleshoot and repair the VM.

  2. Start Rescue for a VM and Prevent Automatic Mounting:

    If you don't want the disks to be mounted automatically, use the --no-mount flag:

    virt-rescue --no-mount vm1

    This will boot the rescue environment without mounting the VM's virtual disks. You will need to mount the disks manually.

  3. Verbose Output:

    To get more detailed output about the rescue process, including logs, use the -v flag:

    virt-rescue -v vm1
  4. Automatically Attempt to Repair Disk Errors:

    In some cases, virt-rescue can automatically attempt to mount the VM's disks and perform disk repairs. You can do this by using the --autorescue option:

    virt-rescue --autorescue vm1

What Happens During virt-rescue

  • Disk Mounting: When you run virt-rescue, it attempts to mount the virtual machine's disks. This allows you to access the VM's file system and make necessary repairs.

  • Minimal Environment: virt-rescue starts a minimal Linux environment with basic tools (like a rescue shell, chroot, file system repair utilities). You can then use these tools to fix issues in the VM.

  • Filesystem Repair: Once inside the rescue environment, you can run commands like fsck to check and repair file system issues or manually fix boot problems.

  • Mounting Virtual Disks: The tool will automatically detect the virtual machine's disk images (such as .qcow2 or .raw) and attempt to mount them.

  • Network Access: If you need to download files or access remote repositories, you can configure network access within the rescue environment.

Example Workflow for Using virt-rescue

  1. Start the Rescue Environment:

    If a VM named vm1 is not booting properly, start the rescue environment:

    virt-rescue vm1
  2. Check Disk for Errors:

    Once inside the rescue shell, you can check the VM's disk for file system errors using fsck:

    fsck /dev/vda1
  3. Repair Configuration Files:

    If a boot configuration file (like /etc/fstab) is corrupted, you can manually edit it. For example:

    nano /mnt/sysimage/etc/fstab
  4. Chroot Into the VM:

    If necessary, you can change the root environment to the mounted VM filesystem using chroot:

    chroot /mnt/sysimage

    This allows you to run commands as if you're operating inside the VM, making it easier to fix configuration issues, install missing packages, or update boot settings.

  5. Exit and Reboot the VM:

    After fixing the issues, exit the rescue environment and reboot the virtual machine:

    exit
    reboot

Use Cases for virt-rescue

  1. Fix Boot Failures: When a VM fails to boot due to disk errors, missing files, or incorrect configurations, virt-rescue can help you troubleshoot and restore it to a bootable state.

  2. Filesystem Corruption: If the VM's filesystem has been corrupted, virt-rescue allows you to repair the filesystem without needing to bring the VM back online.

  3. Misconfigurations: For VMs with misconfigured boot parameters, corrupted system files, or broken network configurations, virt-rescue provides the necessary tools to resolve these issues.

  4. Disaster Recovery: In the event of a failed VM or virtualized environment, virt-rescue can be a crucial part of your disaster recovery plan to bring the system back online quickly.

Security Considerations

  • Access Control: virt-rescue should only be used by authorized personnel, as it allows direct access to the VM’s file system and system configuration.

  • Data Integrity: Always ensure that you're working with the correct disk images to avoid unintentional data loss or corruption.

Conclusion

virt-rescue is a powerful tool that provides a rescue environment for virtual machines that are not booting or are experiencing file system or boot-related issues. By allowing administrators to mount, inspect, and repair virtual disks, it offers a crucial recovery option in virtualized environments. Whether the problem is a corrupted disk, a misconfigured bootloader, or missing system files, virt-rescue can help restore the VM to a functional state.

Last updated