libvirt
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.
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.
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 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.
libguestfs is shipped through 4 packages:
libguestfs0
: which provides
the main C library
guestfs-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:
tux >
sudo
zypper in guestfs-tools
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
.
Guestfs tools support various 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 openSUSE Leap.
virt-rescue
#Edit source
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
virt-resize
#Edit source
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:
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 -
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
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.
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 -
Bring up the VM Guest using the new disk image and confirm correct operation before deleting the old image.
There are guestfs tools to simplify administrative tasks—such as viewing and editing files, or obtaining information on the virtual machine.
virt-filesystems
#Edit sourceThis 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 -
virt-ls
#Edit source
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 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
[...]
virt-cat
#Edit source
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
virt-df
#Edit source
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 actually being used.
tux >
virt-df -a sles.qcow2
Filesystem 1K-blocks Used Available Use%
sles.qcow2:/dev/sda1 16381864 520564 15022492 4%
virt-edit
#Edit source
virt-edit
is a command line tool capable of editing
files that reside in the named virtual machine (or disk image).
virt-tar-in/out
#Edit source
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
virt-copy-in/out
#Edit source
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
virt-log
#Edit source
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.
tux >
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>
...
guestfish
#Edit source
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
Libguestfs provides tools to help converting Xen virtual machines or physical machines into KVM guests. The following section will cover 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 openSUSE Leap. 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
tools on the machine.
Install the needed packages with the command:
tux >
sudo
zypper in virt-p2v kiwi-desc-isoboot
These steps will 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, see man virt-p2v-make-kiwi
.
Create a KIWI configuration:
tux >
virt-p2v-make-kiwi -o /tmp/p2v.kiwi
The -o
defines where to create the KIWI configuration.
Edit the config.xml
file in the generated
configuration if needed. For example, in
config.xml
adjust the keyboard layout of the
live system.
Build the ISO image with kiwi
:
tux >
kiwi --build /tmp/p2v.kiwi1 \
-d /tmp/build2 \
--ignore-repos \
--add-repo http://URL/TO/SLE/REPOSITORIES3 \
--type iso
Burn the ISO on a DVD or a USB stick. With such a medium, boot the machine to be converted.
After the system is started, you will be asked for 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.
If not defined, the created disk image format will be 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 will place 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 will create a new
libvirt-handled guest with the disk image placed in the pool
defined in the field.
Click
to start it.When using the guestfs tools on an image with Btrfs root partition (the default with openSUSE Leap) the following error message may be displayed:
tux >
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 filesystems 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 filesystems 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 usually 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:
tux >
virt-ls -m /dev/sda2:/:subvol=@/.snapshots/2/snapshot -a /path/to/sles12sp2.qcow2 /
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.
libguestfs-test-tool
#Edit source
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 =====