Using libguestfs to easily access Linux virtual machine file systems

Libguestfs is a library on Linux that helps you access and modify virtual machine disk images. You can then run Linux commands and troubleshoot the machine image from the libguestfs shell or host operating system. Learn how to navigate libguestfs, and what to avoid changing or opening in these files to prevent corruption.

Imagine that your virtual machine (VM) won't boot because a major configuration file in the VM is damaged. You will have a hard time accessing and repairing that configuration file, especially because there is no standard yet in the way the virtual machine image file is created. Libguestfs provides a solution.

Libguestfs is a library that helps you in accessing and modifying VM disk images. You can easily install the software in Fedora 11 and later, binary packages are available for other Linux distributions. After installing it (just run YUM and install '*guestfs*' guestfish on Fedora 11), you'll have lots of commands available that help you working on virtual machine image files.

At the back end, Libguestfs helps you in accessing most of the common Linux file systems, such as Ext2/3 and 4, Btrfs and NTFS. More important: you can also use it with most of the common image file types, such as qcow2 for KVM environments, and vmdk if you're working with VMware disk files.

When working with libguestfs, you first make the image file accessible, using the guestfish command:

guestfish --ro -i server.img

Next, the libguestfs shell opens -- you will recognize its <fs> prompt. From this shell you can run any common Linux command, such as the lvdisplay command that shows logical volumes within the image file, or other common Linux utilities, such as cat and vi. But using the guestfish shell isn't the only access method. Instead, you can use libguestfs commands from your host operating system. Among the most useful is the guestmount command. Using this command, the FUSE file system is used to access image file directly from the host operating system. But it is not wise to do this from an operational virtual machine, as you risk conflicts in disk access. For example, if you want to access files on a Windows guest directly, you can use the following guestmount command:

guestmount -a windows.img -m /dev/sda1 --ro /mnt
...if you mount a file system of an active virtual machine in read/write mode you have a high risk of corrupting the virtual machine image.

In this command a Windows image is used as the input image file. From there, the first partition on the first hard disk (commonly known from the Linux host as /dev/sda1) is mounted in read-only mode on the /mnt directory. You can omit the --ro flag to mount in read/write mode, but if you mount a file system of an active virtual machine in read/write mode you have a high risk of corrupting the virtual machine image.

Apart from the guestfish and guestmount, the libguestfs package comes with many other commands. Most of these commands are created for particular tasks, such as virt-edit, which allows you to edit a file in an image file directly from the host operating system. Other useful commands are virt-win-reg, which helps you exporting and merging Windows registry keys, or virt-rescue, which opens the image file in rescue mode, thus allowing you to make modifications directly in the image file that help you making it accessible again.

Libguestfs code recipes

The problem with advanced tools such as those that you find in the libguestfs package, is that they often are very advanced and powerful and therefore difficult to use. The libguestfs project helps you by providing some libguestfs recipes. By using them, you can perform difficult tasks by following the steps that are listed. The recipes are provided as shell scripts to perform a specific task, such as the tar2vm.sh script, that helps you in writing a virtual machine to a tarball. Because they are shell scripts, there is nothing that prevents you from modifying them yourself, thus transforming them to scripts that provide additional functionality.

Accessing virtual machine guest files from a host operating system has always been difficult. Libguestfs makes it a lot easier, by providing a versatile method to open virtual machine disk file, no matter which virtualization technique has been used to create them, or what file system is used within the virtual machine. Currently, libguestfs is available for Fedora and Ubuntu only, it is likely however that we'll see this useful solution on other distributions as well very soon.

About the author:
Sander van Vugt is an author and independent technical trainer, specializing in Linux since 1994. Vugt is also a technical consultant for high-availability (HA) clustering and performance optimization, as well as an expert on SLED 10 administration. 

Dig Deeper on Linux servers