20 libguestfs #
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 a 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.
Using libguestfs tools is fully supported on the AMD64/Intel 64 architecture only.
20.1 VM Guest manipulation overview #
20.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 tools to access, edit and write to these files. When used correctly, such tools can be an important part of guest administration. 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.
20.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 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 or P2V migrations, performing backups, cloning VM Guests, formatting disks, and resizing disks.
You must not use libguestfs tools on live virtual machines. Doing so may result in disk corruption in the VM Guest. libguestfs tools try to stop you from doing this, but cannot catch all cases.
However, most commands have the --ro
(read-only)
option. With this option, you can run a command on a live virtual
machine. The results may be strange or inconsistent but you do not
risk disk corruption.
20.2 Package installation #
libguestfs is shipped through 4 packages:
libguestfs0
: which provides the main C libraryguestfs-data
: which contains the appliance files 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.guestfs-winsupport
: provides support for Windows file guests in the guestfs tools. This package only needs to be installed to handle Windows guests, for example when converting a Windows guest to KVM.
To install guestfs tools on your system run:
>
sudo
zypper in guestfs-tools
20.3 Guestfs tools #
20.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 create an appliance on the fly
using the packages installed on the machine and the files found in
/usr/lib64/guestfs
.
20.3.2 Supported file systems and disk images #
Guestfs tools support multiple file systems including:
Ext2, Ext3, Ext4
Xfs
Btrfs
Multiple disk image formats are also supported:
raw
qcow2
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 Server.
20.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 several simple recovery tools which can
be used to examine and correct problems within a virtual machine or
disk image.
>
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
20.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.
Full step-by-step example: how to expand a virtual machine disk
First, with virtual machine powered off, determine the size of the partitions available on this virtual machine:
>
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 -virt-resize
cannot do in-place disk modifications—there must be sufficient space to store the resized output disk. Use thetruncate
command to create a file of suitable size:>
truncate -s 32G outdisk.imgUse
virt-resize
to resize the disk image.virt-resize
requires two mandatory parameters for the input and output images:>
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.Confirm the image was resized properly:
>
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 -Bring up the VM Guest using the new disk image and confirm correct operation before deleting the old image.
20.3.5 Other virt-* tools #
There are guestfs tools to simplify administrative tasks—such as viewing and editing files, or obtaining information on the virtual machine.
20.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.
>
virt-filesystems -l -a sles.qcow2
Name Type VFS Label Size Parent
/dev/sda1 filesystem ext3 - 17178820608 -
20.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.
>
virt-ls -h -lR -a sles.qcow2 /var/log/
d 0755 776 /var/log
- 0640 0 /var/log/NetworkManager
- 0644 23K /var/log/Xorg.0.log
- 0644 23K /var/log/Xorg.0.log.old
d 0700 482 /var/log/YaST2
- 0644 512 /var/log/YaST2/_dev_vda
- 0644 59 /var/log/YaST2/arch.info
- 0644 473 /var/log/YaST2/config_diff_2017_05_03.log
- 0644 5.1K /var/log/YaST2/curl_log
- 0644 1.5K /var/log/YaST2/disk_vda.info
- 0644 1.4K /var/log/YaST2/disk_vda.info-1
[...]
20.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 specified by its
absolute path, starting at the root directory with
/
.
>
virt-cat -a sles.qcow2 /etc/fstab
devpts /dev/pts devpts mode=0620,gid=5 0 0
proc /proc proc defaults 0 0
20.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 not
only displays the size of disk allocated to a virtual machine, but
can look inside disk images to show how much space is being used.
>
virt-df -a sles.qcow2
Filesystem 1K-blocks Used Available Use%
sles.qcow2:/dev/sda1 16381864 520564 15022492 4%
20.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).
20.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.
>
virt-tar-out -a sles.qcow2 /home homes.tar
20.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.
>
virt-copy-in -a sles.qcow2 data.tar /tmp/>
virt-ls -a sles.qcow2 /tmp/ .ICE-unix .X11-unix data.tar
20.3.5.8 virt-log
#
virt-log
shows the log files of the named libvirt
domain, virtual machine or disk image. If the package
guestfs-winsupport is installed it can also show
the event log of a Windows virtual machine disk image.
>
virt-log -a windows8.qcow2
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<Events>
<Event xmlns="http://schemas.microsoft.com/win/2004/08/events/event"><System><Provider Name="EventLog"></Provider>
<EventID Qualifiers="32768">6011</EventID>
<Level>4</Level>
<Task>0</Task>
<Keywords>0x0080000000000000</Keywords>
<TimeCreated SystemTime="2014-09-12 05:47:21"></TimeCreated>
<EventRecordID>1</EventRecordID>
<Channel>System</Channel>
<Computer>windows-uj49s6b</Computer>
<Security UserID=""></Security>
</System>
<EventData><Data><string>WINDOWS-UJ49S6B</string>
<string>WIN-KG190623QG4</string>
</Data>
<Binary></Binary>
</EventData>
</Event>
...
20.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 the functionality of the guestfs API.
Examples of usage:
>
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
20.3.7 Converting a physical machine into a KVM guest #
Libguestfs provides tools to help converting Xen virtual machines or physical machines into KVM guests. The Xen to KVM conversion scenario is covered by the Chapter 17, Xen to KVM migration guide. The following section covers a special use case: converting a bare metal machine into a KVM one.
Converting a physical machine into a KVM one is not yet supported in SUSE Linux Enterprise Server. This feature is released as a technology preview only.
Converting a physical machine requires collecting information about it
and transmitting this to a conversion server. This is achieved by
running a live system prepared with virt-p2v
and
KIWI NG tools on the machine.
Install the needed packages with the command:
>
sudo
zypper in virt-p2v kiwi-desc-isobootNoteThese steps document how to create an ISO image to create a bootable DVD. Alternatively, you can create a PXE boot image instead; for more information about building PXE images with KIWI NG, see
man virt-p2v-make-kiwi
.Create a KIWI NG configuration:
>
virt-p2v-make-kiwi -o /tmp/p2v.kiwiThe
-o
defines where to create the KIWI NG configuration.Edit the
config.xml
file in the generated configuration if needed. For example, inconfig.xml
adjust the keyboard layout of the live system.Build the ISO image with
kiwi
:>
kiwi --build /tmp/p2v.kiwi1 \ -d /tmp/build2 \ --ignore-repos \ --add-repo http://URL_TO_REPOSITORIES3 \ --type isoBurn the ISO on a DVD or a USB stick. With such a medium, boot the machine to be converted.
After the system is started, enter the connection details of the conversion server. This server is a machine with the
virt-v2v
package installed.If the network setup is more complex than a DHCP client, click the
button to open the YaST network configuration dialog.Click the
button to allow moving to the next page of the wizard.Select the disks and network interfaces to be converted and define the VM data like the amount of allocated CPUs, memory and the Virtual Machine name.
NoteIf not defined, the created disk image format is raw by default. This can be changed by entering the desired format in the field.
There are two possibilities to generate the virtual machine: either using the local or the libvirt output. The first one places the Virtual Machine disk image and configuration in the path defined in the field. These can then be used to define a new libvirt-handled guest using
virsh
. The second method creates a new libvirt-handled guest with the disk image placed in the pool defined in the field.Click
to start it.
20.4 Troubleshooting #
20.4.1 Btrfs-related problems #
When using the guestfs tools on an image with Btrfs root partition (the default with SUSE Linux Enterprise Server) the following error message may be displayed:
>
virt-ls -a /path/to/sles12sp2.qcow2 /
virt-ls: multi-boot operating systems are not supported
If using guestfish '-i' option, remove this option and instead
use the commands 'run' followed by 'list-filesystems'.
You can then mount file systems you want by hand using the
'mount' or 'mount-ro' command.
If using guestmount '-i', remove this option and choose the
filesystem(s) you want to see by manually adding '-m' option(s).
Use 'virt-filesystems' to see what file systems are available.
If using other virt tools, multi-boot operating systems won't work
with these tools. Use the guestfish equivalent commands
(see the virt tool manual page).
This is often caused by the presence of snapshots in the guests. In
this case guestfs does not know which snapshot to bootstrap. To force
the use of a snapshot, use the -m
parameter as
follows:
>
virt-ls -m /dev/sda2:/:subvol=@/.snapshots/2/snapshot -a /path/to/sles12sp2.qcow2 /
20.4.2 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.
20.4.3 libguestfs-test-tool
#
libguestfs-test-tool
is a test program that checks
if basic libguestfs functionality is working. It prints 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 =====