Chapter 22. Guest Virtual Machine Disk Access with Offline Tools

22.1. Introduction

Red Hat Enterprise Linux 7 provides a number of libguestfs utilities that enable accessing, editing, and creating guest virtual machine disks or other disk images. There are multiple uses for these tools, including:
  • Viewing or downloading files located on a guest virtual machine disk.
  • Editing or uploading files on a guest virtual machine disk.
  • Reading or writing guest virtual machine configuration.
  • Preparing new disk images containing files, directories, file systems, partitions, logical volumes and other options.
  • Rescuing and repairing guest virtual machines that fail to boot or those that need boot configuration changes.
  • Monitoring disk usage of guest virtual machines.
  • Auditing compliance of guest virtual machines, for example to organizational security standards.
  • Deploying guest virtual machines by cloning and modifying templates.
  • Reading CD and DVD ISO images and floppy disk images.

Warning

You must never use the utilities listed in this chapter to write to a guest virtual machine or disk image that is attached to a running virtual machine, not even to open such a disk image in write mode.
Doing so will result in disk corruption of the guest virtual machine. The tools try to prevent you from doing this, but do not secure all cases. If there is any suspicion that a guest virtual machine might be running, Red Hat strongly recommends not using the utilities.
For increased safety, certain utilities can be used in read-only mode (using the --ro option), which does not save the changes.

Note

The primary source for documentation for libguestfs and the related utilities are the Linux man pages. The API is documented in guestfs(3), guestfish is documented in guestfish(1), and the virtualization utilities are documented in their own man pages (such as virt-df(1)). For troubleshooting information, refer to Section A.18, “libguestfs Troubleshooting”

22.1.1. Caution about Using Remote Connections

Some virtualization commands in Red Hat Enterprise Linux 7 allow you to specify a remote libvirt connection. For example:
# virt-df -c  qemu://remote/system -d Guest
However, libguestfs utilities in Red Hat Enterprise Linux 7 cannot access the disks of remote libvirt guests, and commands using remote URLs as shown above do not work as expected.
Nevertheless, beginning with Red Hat Enterprise Linux 7, libguestfs can access remote disk sources over network block device (NBD). You can export a disk image from a remote machine using the qemu-nbd command, and access it using a nbd:// URL. You may need to open a port on your firewall (port 10809) as shown here:
On the remote system: qemu-nbd -t disk.img
On the local system: virt-df -a nbd://remote
The following libguestfs commands are affected:
  • guestfish
  • guestmount
  • virt-alignment-scan
  • virt-cat
  • virt-copy-in
  • virt-copy-out
  • virt-df
  • virt-edit
  • virt-filesystems
  • virt-inspector
  • virt-ls
  • virt-rescue
  • virt-sysprep
  • virt-tar-in
  • virt-tar-out
  • virt-win-reg