Applies to openSUSE Leap 42.1

17 libguestfs

Abstract

Virtual Machines consist of disk images and definition files. Manually accessing and manipulating these guest components (outside of normal hypervisor processes) is possible, but inherently dangerous and risks compromising data integrity. libguestfs is a C library and corresponding set of tools designed for safely accessing and modifying Virtual Machine disk images - outside of normal hypervisor processes, but without the risk normally associated with manual editing.

17.1 VM Guest Manipulation Overview

17.1.1 VM Guest Manipulation Risk

As disk images and definition files are simply another type of file in a Linux environment, it is possible to use many different tools to access, edit and write to these files. When used correctly, such tools can be an important part of guest adminitration. However, even correct usage of these tools is not without risk. Risks that should be considered when manually manipulating guest disk images include:

  • Data Corruption: Concurrently accessing images, by the host machine or another node in a cluster, can cause changes to be lost or data corruption to occur if virtualization protection layers are bypassed.

  • Security: Mounting disk images as loop devices requires root access. While an image is loop mounted, other users and processes can potentially access the disk contents.

  • Administrator Error: Bypassing virtualization layers correctly requires advanced understanding of virtual components and tools. Failing to isolate the images or failing to clean up properly after changes have been made can lead to further problems once back in virtualization control.

17.1.2 libguestfs Design

libguestfs C library has been designed to safely and securely create, access and modify virtual machine (VM Guest) disk images. It also provides additional language bindings: for Perl, Python, PHP (only for 64-bit machines), and Ruby. libguestfs can access VM Guest disk images without needing root and with multiple layers of defense against rogue disk images.

libguestfs provides many different tools designed for accessing and modifying VM Guest disk images and contents. These tools provide such capabilities as: viewing and editing files inside guests, scripting changes to VM Guests, monitoring disk used/free statistics, creating guests, doing V2V migrations, performing backups, cloning VM Guests, formatting disks, and resizing disks.

Warning
Warning: Best Practices

You must not use libguestfs tools on live virtual machines. Doing so will probably result in disk corruption in the VM Guest. libguestfs tools try to stop you from doing this, but cannot catch all cases.

However most command have the --ro (read-only) option. With this option, you can attach a command to a live virtual machine. The results might be strange or inconsistent at times but you will not risk disk corruption.

17.2 Package Installation

libguestfs is shipped through 3 packages:

  • libguestfs0: which provides the main C library

  • guestfs-data: which contains the kernel and initrd used when launching images (stored in /usr/lib64/guestfs)

  • guestfs-tools: the core guestfs tools, man pages, and the /etc/libguestfs-tools.conf configuration file.

To install guestfs tools on your system run:

zypper in guestfs-tools

17.3 Guestfs Tools

17.3.1 Modifying Virtual Machines

The set of tools found within the guestfs-tools package is used for accessing and modifying virtual machine disk images. This functionality is provided through a familiar shell interface with built-in safeguards which ensure image integrity. Guestfs tools shells expose all capabilities of the guestfs API, and use the kernel and initrd found in /usr/lib4/guestfs.

17.3.2 Supported File Systems and Disk Images

Guestfs tools support various file systems including:

  • Ext2, Ext3, Ext4

  • Xfs

  • Brtfs

Multiple disk image formats are also supported:

  • raw

  • qcow2

Warning
Warning: Unsupported File System

Guestfs may also support Windows* file systems (VFAT, NTFS), BSD* and Apple* file systems, and other disk image formats (VMDK, VHDX...). However, these file systems and disk image formats are unsupported on SUSE Linux Enterprise.

17.3.3 virt-rescue

virt-rescue is similar to a rescue CD, but for virtual machines, and without the need for a CD. virt-rescue presents users with a rescue shell and some simple recovery tools which can be used to examine and correct problems within a virtual machine or disk image.

tux >  virt-rescue -a sles.qcow2 
Welcome to virt-rescue, the libguestfs rescue shell.

Note: The contents of / are the rescue appliance.
You need to mount the guest's partitions under /sysroot
before you can examine them. A helper script for that exists:
mount-rootfs-and-do-chroot.sh /dev/sda2

><rescue> 
[   67.194384] EXT4-fs (sda1): mounting ext3 file system
using the ext4 subsystem
[   67.199292] EXT4-fs (sda1): mounted filesystem with ordered data
mode. Opts: (null)
mount: /dev/sda1 mounted on /sysroot.
mount: /dev bound on /sysroot/dev.
mount: /dev/pts bound on /sysroot/dev/pts.
mount: /proc bound on /sysroot/proc.
mount: /sys bound on /sysroot/sys.
Directory: /root
Thu Jun  5 13:20:51 UTC 2014
(none):~ #

You are now running the VM Guest in rescue mode:

(none):~ # cat /etc/fstab 
devpts  /dev/pts          devpts  mode=0620,gid=5 0 0
proc    /proc             proc    defaults        0 0
sysfs   /sys              sysfs   noauto          0 0
debugfs /sys/kernel/debug debugfs noauto          0 0
usbfs   /proc/bus/usb     usbfs   noauto          0 0
tmpfs   /run              tmpfs   noauto          0 0
/dev/disk/by-id/ata-QEMU_HARDDISK_QM00001-part1 / ext3 defaults 1 1

17.3.4 virt-resize

virt-resize is used to resize a virtual machine disk, making it larger or smaller overall, and resizing or deleting any partitions contained within.

Procedure 17.1: Expanding a Disk

Full step-by-step example: How to expand a virtual machine disk

  1. First, with virtual machine powered off, determine the size of the partitions available on this virtual machine:

    tux >  virt-filesystems --long --parts --blkdevs -h -a sles.qcow2
    Name       Type       MBR  Size  Parent
    /dev/sda1  partition  83   16G   /dev/sda
    /dev/sda   device     -    16G   -
  2. virt-resize cannot do in-place disk modifications—there must be sufficient space to store the resized output disk. Use the truncate command to create a file of suitable size:

    tux >  truncate -s 32G outdisk.img
  3. Use virt-resize to resize the disk image. virt-resize requires two mandatory parameters for the input and output images:

    tux >  virt-resize --expand /dev/sda1 sles.qcow2 outdisk.img
    Examining sles.qcow2 ...
    **********
    Summary of changes:
    
    /dev/sda1: This partition will be resized from 16,0G to 32,0G.  The 
        filesystem ext3 on /dev/sda1 will be expanded using the 'resize2fs' 
        method.
    
    **********
    Setting up initial partition table on outdisk.img ...
    Copying /dev/sda1 ...
    ◐ 84%
    ⟦▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒════════⟧ 00:03
    Expanding /dev/sda1 using the 'resize2fs' method ...
    
    Resize operation completed with no errors.  Before deleting the old 
    disk, carefully check that the resized disk boots and works correctly.
  4. Confirm the image was resized properly:

    tux >  virt-filesystems --long --parts --blkdevs -h -a outdisk.img
    Name       Type       MBR  Size  Parent
    /dev/sda1  partition  83   32G   /dev/sda
    /dev/sda   device     -    32G   -
  5. Bring up the VM Guest using the new disk image and confirm correct operation before deleting the old image.

17.3.5 Other virt-* Tools

Various other guestfs tools exist to simplify administrative tasks—such as viewing and editing files, or obtaining information on the virtual machine.

17.3.5.1 virt-filesystems

This tool is used to report information regarding file systems, partitions, and logical volumes in a disk image or virtual machine.

tux >  virt-filesystems -l -a sles.qcow2 
Name       Type        VFS   Label  Size         Parent
/dev/sda1  filesystem  ext3  -      17178820608  -

17.3.5.2 virt-ls

virt-ls lists file names, file sizes, checksums, extended attributes and more from a virtual machine or disk image. Multiple directory names can be given, in which case the output from each is concatenated. To list directories from a libvirt guest, use the -d option to specify the name of the guest. For a disk image, use the -a option.

tux >  virt-ls -h -lR -a sles.qcow2 /var/log/ 
d 0755       4,0K /var/log/
d 0700       4,0K /var/log//YaST2
- 0644       1,9K /var/log//YaST2/mkinitrd.log
- 0644        496 /var/log//YaST2/perl-BL-standalone-log
- 0600       3,2K /var/log//faillog
d 0700       4,0K /var/log//krb5
- 0644        29K /var/log//lastlog
- 0644        496 /var/log//pbl.log
- 0664          0 /var/log//wtmp
d 0755       4,0K /var/log//zypp

17.3.5.3 virt-cat

virt-cat is a command line tool to display the contents of a file that exists in the named virtual machine (or disk image). Multiple file names can be given, in which case they are concatenated together. Each file name must be a full path, starting at the root directory (starting with '/').

tux >  virt-cat -a sles.qcow2 /etc/fstab
devpts /dev/pts devpts mode=0620,gid=5 0 0 
proc   /proc    proc   defaults        0 0

17.3.5.4 virt-df

virt-df is a command line tool to display free space on virtual machine file systems. Unlike other tools, it does not just display the size of disk allocated to a virtual machine, but can look inside disk images to show how much space is actually being used.

tux >  virt-df -a sles.qcow2 
Filesystem                           1K-blocks       Used  Available  Use%
sles.qcow2:/dev/sda1                  16381864     520564   15022492  4%

17.3.5.5 virt-edit

virt-edit is a command line tool capable of editing files that reside in the named virtual machine (or disk image).

17.3.5.6 virt-tar-in/out

virt-tar-in unpacks an uncompressed TAR archive into a virtual machine disk image or named libvirt domain. virt-tar-out packs a virtual machine disk image directory into a TAR archive.

tux >  virt-tar-out -a sles.qcow2 /home homes.tar

17.3.5.7 virt-copy-in/out

virt-copy-in copies files and directories from the local disk into a virtual machine disk image or named libvirt domain. virt-copy-out copies files and directories out of a virtual machine disk image or named libvirt domain.

tux >  virt-copy-in -a sles.qcow2 data.tar /tmp/
virt-ls -a sles.qcow2 /tmp/
.ICE-unix
.X11-unix
data.tar

17.3.6 guestfish

guestfish is a shell and command line tool for examining and modifying virtual machine file systems. It uses libguestfs and exposes all of the functionality of the guestfs API.

Examples of usage:

tux >  guestfish -a disk.img <<EOF
run
list-filesystems
EOF
guestfish 

Welcome to guestfish, the guest filesystem shell for
editing virtual machine filesystems and disk images.

Type: 'help' for help on commands
      'man' to read the manual
      'quit' to quit the shell

><fs> add sles.qcow2
><fs> run
><fs> list-filesystems 
/dev/sda1: ext3
><fs> mount /dev/sda1 /
 cat /etc/fstab 
devpts  /dev/pts          devpts  mode=0620,gid=5 0 0
proc    /proc             proc    defaults        0 0
sysfs   /sys              sysfs   noauto          0 0
debugfs /sys/kernel/debug debugfs noauto          0 0
usbfs   /proc/bus/usb     usbfs   noauto          0 0
tmpfs   /run              tmpfs   noauto          0 0
/dev/disk/by-id/ata-QEMU_HARDDISK_QM00001-part1 / ext3 defaults 1 1

17.4 Troubleshooting

17.4.1 Environment

When troubleshooting problems within a libguestfs appliance, the environment variable LIBGUESTFS_DEBUG=1 can be used to enable debug messages. To output each command/API call in a format that is similar to guestfish commands, use the environment variable LIBGUESTFS_TRACE=1.

17.4.2 libguestfs-test-tool

libguestfs-test-tool is a test program that checks if basic libguestfs functionality is working. It will print a large amount of diagnostic messages and details of the guestfs environment, then create a test image and try to start it. If it runs to completion successfully, the following message should be seen near the end:

===== TEST FINISHED OK =====

17.5 External References

Print this page