Applies to SUSE Linux Enterprise Server 15 SP2

31 Guest Installation #

The libvirt-based tools such as virt-manager and virt-install offer convenient interfaces to set up and manage virtual machines. They act as a kind of wrapper for the qemu-system-ARCHcommand. However, it is also possible to use qemu-system-ARCH directly without using libvirt-based tools.

Warning: qemu-system-ARCH and libvirt

Virtual Machines created with qemu-system-ARCH are not "visible" for the libvirt-based tools.

31.1 Basic Installation with `qemu-system-ARCH` #

In the following example, a virtual machine for a SUSE Linux Enterprise Server 11 installation is created. For detailed information on the commands, refer to the respective man pages.

If you do not already have an image of a system that you want to run in a virtualized environment, you need to create one from the installation media. In such case, you need to prepare a hard disk image, and obtain an image of the installation media or the media itself.

Create a hard disk with qemu-img.

> qemu-img create1 -f raw2 /images/sles/hda3 8G4

1	The subcommand `create` tells `qemu-img` to create a new image.
2	Specify the disk's format with the `-f` parameter.
3	The full path to the image file.
4	The size of the image—8 GB in this case. The image is created as a Sparse image file file that grows when the disk is filled with data. The specified size defines the maximum size to which the image file can grow.

After at least one hard disk image is created, you can set up a virtual machine with qemu-system-ARCH that will boot into the installation system:

# qemu-system-x86_64 -name "sles"1-machine accel=kvm -M pc2 -m 7683 \
-smp 24 -boot d5 \
-drive file=/images/sles/hda,if=virtio,index=0,media=disk,format=raw6 \
-drive file=/isos/SLE-15-SP2-Online-ARCH-GM-media1.iso,index=1,media=cdrom7 \
-net nic,model=virtio,macaddr=52:54:00:05:11:118 -net user \
-vga cirrus9 -balloon virtio10

1	Name of the virtual machine that will be displayed in the window caption and be used for the VNC server. This name must be unique.
2	Specifies the machine type. Use `qemu-system-ARCH` `-M ?` to display a list of valid parameters. `pc` is the default Standard PC.
3	Maximum amount of memory for the virtual machine.
4	Defines an SMP system with two processors.
5	Specifies the boot order. Valid values are `a`, `b` (floppy 1 and 2), `c` (first hard disk),`d` (first CD-ROM), or `n` to `p` (Ether-boot from network adapter 1-3). Defaults to `c`.
6	Defines the first (`index=0`) hard disk. It will be accessed as a paravirtualized (`if=virtio`) drive in `raw` format.
7	The second (`index=1`) image drive will act as a CD-ROM.
8	Defines a paravirtualized (`model=virtio`) network adapter with the MAC address `52:54:00:05:11:11`. Be sure to specify a unique MAC address, otherwise a network conflict may occur.
9	Specifies the graphic card. If you specify `none`, the graphic card will be disabled.
10	Defines the paravirtualized balloon device that allows to dynamically change the amount of memory (up to the maximum value specified with the parameter `-m`).

After the installation of the guest operating system finishes, you can start the related virtual machine without the need to specify the CD-ROM device:

# qemu-system-x86_64 -name "sles" -machine type=pc,accel=kvm -m 768 \
-smp 2 -boot c \
-drive file=/images/sles/hda,if=virtio,index=0,media=disk,format=raw \
-net nic,model=virtio,macaddr=52:54:00:05:11:11 \
-vga cirrus -balloon virtio

31.2 Managing Disk Images with `qemu-img` #

In the previous section (see Section 31.1, “Basic Installation with qemu-system-ARCH”), we used the qemu-img command to create an image of a hard disk. You can, however, use qemu-img for general disk image manipulation. This section introduces qemu-img subcommands to help manage the disk images flexibly.

31.2.1 General Information on qemu-img Invocation #

qemu-img uses subcommands (like zypper does) to do specific tasks. Each subcommand understands a different set of options. Some options are general and used by more of these subcommands, while some are unique to the related subcommand. See the qemu-img manual page (man 1 qemu-img) for a list of all supported options. qemu-img uses the following general syntax:

> qemu-img subcommand [options]

and supports the following subcommands:

create: Creates a new disk image on the file system.
check: Checks an existing disk image for errors.
compare: Check if two images have the same content.
map: Dumps the metadata of the image file name and its backing file chain.
amend: Amends the image format specific options for the image file name.
convert: Converts an existing disk image to a new one in a different format.
info: Displays information about the relevant disk image.
snapshot: Manages snapshots of existing disk images.
commit: Applies changes made to an existing disk image.
rebase: Creates a new base image based on an existing image.
resize: Increases or decreases the size of an existing image.

31.2.2 Creating, Converting and Checking Disk Images #

This section describes how to create disk images, check their condition, convert a disk image from one format to another, and get detailed information about a particular disk image.

31.2.2.1 qemu-img create #

Use qemu-img create to create a new disk image for your VM Guest operating system. The command uses the following syntax:

> qemu-img create -f fmt1 -o options2 fname3 size4

1	The format of the target image. Supported formats are `raw` and `qcow2`.
2	Some image formats support additional options to be passed on the command line. You can specify them here with the `-o` option. The `raw` image format supports only the `size` option, so it is possible to insert `-o size=8G` instead of adding the size option at the end of the command.
3	Path to the target disk image to be created.
4	Size of the target disk image (if not already specified with the `-o size=<image_size>` option. Optional suffixes for the image size are `K` (kilobyte), `M` (megabyte), `G` (gigabyte), or `T` (terabyte).

To create a new disk image sles.raw in the directory /images growing up to a maximum size of 4 GB, run the following command:

> qemu-img create -f raw -o size=4G /images/sles.raw
Formatting '/images/sles.raw', fmt=raw size=4294967296

> ls -l /images/sles.raw
-rw-r--r-- 1 tux users 4294967296 Nov 15 15:56 /images/sles.raw

> qemu-img info /images/sles.raw
image: /images/sles11.raw
file format: raw
virtual size: 4.0G (4294967296 bytes)
disk size: 0

As you can see, the virtual size of the newly created image is 4 GB, but the actual reported disk size is 0 as no data has been written to the image yet.

Tip: VM Guest Images on the Btrfs File System

If you need to create a disk image on the Btrfs file system, you can use nocow=on to reduce the performance overhead created by the copy-on-write feature of Btrfs:

> qemu-img create -o nocow=on test.img 8G

If you, however, want to use copy-on-write (for example for creating snapshots or sharing them across virtual machines), then leave the command line without the nocow option.

31.2.2.2 qemu-img convert #

Use qemu-img convert to convert disk images to another format. To get a complete list of image formats supported by QEMU, run qemu-img -h and look at the last line of the output. The command uses the following syntax:

> qemu-img convert -c1 -f fmt2 -O out_fmt3 -o options4 fname5 out_fname6

1	Applies compression on the target disk image. Only `qcow` and `qcow2` formats support compression.
2	The format of the source disk image. It is usually autodetected and can therefore be omitted.
3	The format of the target disk image.
4	Specify additional options relevant for the target image format. Use `-o ?` to view the list of options supported by the target image format.
5	Path to the source disk image to be converted.
6	Path to the converted target disk image.

> qemu-img convert -O vmdk /images/sles.raw \
/images/sles.vmdk

> ls -l /images/
-rw-r--r-- 1 tux users 4294967296 16. lis 10.50 sles.raw
-rw-r--r-- 1 tux users 2574450688 16. lis 14.18 sles.vmdk

To see a list of options relevant for the selected target image format, run the following command (replace vmdk with your image format):

> qemu-img convert -O vmdk /images/sles.raw \
/images/sles.vmdk -o ?
Supported options:
size             Virtual disk size
backing_file     File name of a base image
compat6          VMDK version 6 image
subformat        VMDK flat extent format, can be one of {monolithicSparse \
    (default) | monolithicFlat | twoGbMaxExtentSparse | twoGbMaxExtentFlat}
scsi             SCSI image

31.2.2.3 qemu-img check #

Use qemu-img check to check the existing disk image for errors. Not all disk image formats support this feature. The command uses the following syntax:

> qemu-img check -f fmt1 fname2

1	The format of the source disk image. It is usually autodetected and can therefore be omitted.
2	Path to the source disk image to be checked.

If no error is found, the command returns no output. Otherwise, the type and number of errors found is shown.

> qemu-img check -f qcow2 /images/sles.qcow2
ERROR: invalid cluster offset=0x2af0000
[...]
ERROR: invalid cluster offset=0x34ab0000
378 errors were found on the image.

31.2.2.4 Increasing the Size of an Existing Disk Image #

When creating a new image, you must specify its maximum size before the image is created (see Section 31.2.2.1, “qemu-img create”). After you have installed the VM Guest and have been using it for some time, the initial size of the image may no longer be sufficient. In that case, add more space to it.

To increase the size of an existing disk image by 2 gigabytes, use:

> qemu-img resize /images/sles.raw +2GB

Note

You can resize the disk image using the formats raw and qcow2. To resize an image in another format, convert it to a supported format with qemu-img convert first.

The image now contains an empty space of 2 GB after the final partition. You can resize the existing partitions or add new ones.

Figure 31.1: New 2 GB Partition in Guest YaST Partitioner #

31.2.2.5 Advanced Options for the qcow2 File Format #

qcow2 is the main disk image format used by QEMU. Its size grows on demand, and the disk space is only allocated when it is actually needed by the virtual machine.

A qcow2 formatted file is organized in units of constant size. These units are called clusters. Viewed from the guest side, the virtual disk is also divided into clusters of the same size. QEMU defaults to 64 kB clusters, but you can specify a different value when creating a new image:

> qemu-img create -f qcow2 -o cluster_size=128K virt_disk.qcow2 4G

A qcow2 image contains a set of tables organized in two levels that are called the L1 and L2 tables. There is just one L1 table per disk image, while there can be many L2 tables depending on how big the image is.

To read or write data to the virtual disk, QEMU needs to read its corresponding L2 table to find out the relevant data location. Because reading the table for each I/O operation consumes system resources, QEMU keeps a cache of L2 tables in memory to speed up disk access.

31.2.2.5.1 Choosing the Right Cache Size #

The cache size relates to the amount of allocated space. L2 cache can map the following amount of virtual disk:

disk_size = l2_cache_size * cluster_size / 8

With the default 64 kB of cluster size, that is

disk_size = l2_cache_size * 8192

Therefore, to have a cache that maps n gigabytes of disk space with the default cluster size, you need

l2_cache_size = disk_size_GB * 131072

QEMU uses 1 MB (1048576 bytes) of L2 cache by default. Following the above formulas, 1 MB of L2 cache covers 8 GB (1048576 / 131072) of virtual disk. This means that the performance is fine with the default L2 cache size if your virtual disk size is up to 8 GB. For larger disks, you can speed up the disk access by increasing the L2 cache size.

31.2.2.5.2 Configuring the Cache Size #

You can use the -drive option on the QEMU command line to specify the cache sizes. Alternatively when communicating via QMP, use the blockdev-add command. For more information on QMP, see Section 33.11, “QMP - QEMU Machine Protocol”.

The following options configure the cache size for the virtual guest:

l2-cache-size: The maximum size of the L2 table cache.
refcount-cache-size: The maximum size of the refcount block cache. For more information on refcount, see https://raw.githubusercontent.com/qemu/qemu/master/docs/qcow2-cache.txt.
cache-size: The maximum size of both caches combined.

When specifying values for the options above, be aware of the following:

The size of both the L2 and refcount block caches needs to be a multiple of the cluster size.
If you only set one of the options, QEMU will automatically adjust the other options so that the L2 cache is 4 times bigger than the refcount cache.

The refcount cache is used much less often than the L2 cache, therefore you can keep it relatively small:

# qemu-system-ARCH [...] \
 -drive file=disk_image.qcow2,l2-cache-size=4194304,refcount-cache-size=262144

31.2.2.5.3 Reducing the Memory Usage #

The larger the cache, the more memory it consumes. There is a separate L2 cache for each qcow2 file. When using a lot of big disk images, you will probably need a considerably large amount of memory. Memory consumption is even worse if you add backing files (Section 31.2.4, “Manipulate Disk Images Effectively”) and snapshots (see Section 31.2.3, “Managing Snapshots of Virtual Machines with qemu-img”) to the guest's setup chain.

That is why QEMU introduced the cache-clean-interval setting. It defines an interval in seconds after which all cache entries that have not been accessed are removed from memory.

The following example removes all unused cache entries every 10 minutes:

# qemu-system-ARCH [...] -drive file=hd.qcow2,cache-clean-interval=600

If this option is not set, the default value is 0 and it disables this feature.

31.2.3 Managing Snapshots of Virtual Machines with qemu-img #

Virtual Machine snapshots are snapshots of the complete environment in which a VM Guest is running. The snapshot includes the state of the processor (CPU), memory (RAM), devices, and all writable disks.

Snapshots are helpful when you need to save your virtual machine in a particular state. For example, after you configured network services on a virtualized server and want to quickly start the virtual machine in the same state you last saved it. Or you can create a snapshot after the virtual machine has been powered off to create a backup state before you try something experimental and possibly make VM Guest unstable. This section introduces the latter case, while the former is described in Chapter 33, Virtual Machine Administration Using QEMU Monitor.

To use snapshots, your VM Guest must contain at least one writable hard disk image in qcow2 format. This device is usually the first virtual hard disk.

Virtual Machine snapshots are created with the savevm command in the interactive QEMU monitor. To make identifying a particular snapshot easier, you can assign it a tag. For more information on QEMU monitor, see Chapter 33, Virtual Machine Administration Using QEMU Monitor.

Once your qcow2 disk image contains saved snapshots, you can inspect them with the qemu-img snapshot command.

Warning: Shut Down the VM Guest

Do not create or delete virtual machine snapshots with the qemu-img snapshot command while the virtual machine is running. Otherwise, you may damage the disk image with the state of the virtual machine saved.

31.2.3.1 Listing Existing Snapshots #

Use qemu-img snapshot -l DISK_IMAGE to view a list of all existing snapshots saved in the disk_image image. You can get the list even while the VM Guest is running.

> qemu-img snapshot -l /images/sles.qcow2
Snapshot list:
ID1       TAG2               VM SIZE3        DATE4          VM CLOCK5
1         booting                4.4M 2013-11-22 10:51:10   00:00:20.476
2         booted                 184M 2013-11-22 10:53:03   00:02:05.394
3         logged_in              273M 2013-11-22 11:00:25   00:04:34.843
4         ff_and_term_running    372M 2013-11-22 11:12:27   00:08:44.965

1	Unique identification number of the snapshot. Usually auto-incremented.
2	Unique description string of the snapshot. It is meant as a human-readable version of the ID.
3	The disk space occupied by the snapshot. Note that the more memory is consumed by running applications, the bigger the snapshot is.
4	Time and date the snapshot was created.
5	The current state of the virtual machine's clock.

31.2.3.2 Creating Snapshots of a Powered-Off Virtual Machine #

Use qemu-img snapshot -c SNAPSHOT_TITLE DISK_IMAGE to create a snapshot of the current state of a virtual machine that was previously powered off.

> qemu-img snapshot -c backup_snapshot /images/sles.qcow2

> qemu-img snapshot -l /images/sles.qcow2
Snapshot list:
ID        TAG                 VM SIZE                DATE       VM CLOCK
1         booting                4.4M 2013-11-22 10:51:10   00:00:20.476
2         booted                 184M 2013-11-22 10:53:03   00:02:05.394
3         logged_in              273M 2013-11-22 11:00:25   00:04:34.843
4         ff_and_term_running    372M 2013-11-22 11:12:27   00:08:44.965
5         backup_snapshot           0 2013-11-22 14:14:00   00:00:00.000

If something breaks in your VM Guest and you need to restore the state of the saved snapshot (ID 5 in our example), power off your VM Guest and execute the following command:

> qemu-img snapshot -a 5 /images/sles.qcow2

The next time you run the virtual machine with qemu-system-ARCH, it will be in the state of snapshot number 5.

Note

The qemu-img snapshot -c command is not related to the savevm command of QEMU monitor (see Chapter 33, Virtual Machine Administration Using QEMU Monitor). For example, you cannot apply a snapshot with qemu-img snapshot -a on a snapshot created with savevm in QEMU's monitor.

31.2.3.3 Deleting Snapshots #

Use qemu-img snapshot -d SNAPSHOT_ID DISK_IMAGE to delete old or unneeded snapshots of a virtual machine. This saves some disk space inside the qcow2 disk image as the space occupied by the snapshot data is restored:

> qemu-img snapshot -d 2 /images/sles.qcow2

31.2.4 Manipulate Disk Images Effectively #

Imagine the following real-life situation: you are a server administrator who runs and manages several virtualized operating systems. One group of these systems is based on one specific distribution, while another group (or groups) is based on different versions of the distribution or even on a different (and maybe non-Unix) platform. To make the case even more complex, individual virtual guest systems based on the same distribution usually differ according to the department and deployment. A file server typically uses a different setup and services than a Web server does, while both may still be based on SUSE® Linux Enterprise Server.

With QEMU it is possible to create “base” disk images. You can use them as template virtual machines. These base images will save you plenty of time because you will never need to install the same operating system more than once.

31.2.4.1 Base and Derived Images #

First, build a disk image as usual and install the target system on it. For more information, see Section 31.1, “Basic Installation with qemu-system-ARCH” and Section 31.2.2, “Creating, Converting and Checking Disk Images”. Then build a new image while using the first one as a base image. The base image is also called a backing file. After your new derived image is built, never boot the base image again, but boot the derived image instead. Several derived images may depend on one base image at the same time. Therefore, changing the base image can damage the dependencies. While using your derived image, QEMU writes changes to it and uses the base image only for reading.

It is a good practice to create a base image from a freshly installed (and, if needed, registered) operating system with no patches applied and no additional applications installed or removed. Later on, you can create another base image with the latest patches applied and based on the original base image.

31.2.4.2 Creating Derived Images #

Note

While you can use the raw format for base images, you cannot use it for derived images because the raw format does not support the backing_file option. Use for example the qcow2 format for the derived images.

For example, /images/sles_base.raw is the base image holding a freshly installed system.

> qemu-img info /images/sles_base.raw
image: /images/sles_base.raw
file format: raw
virtual size: 4.0G (4294967296 bytes)
disk size: 2.4G

The image's reserved size is 4 GB, the actual size is 2.4 GB, and its format is raw. Create an image derived from the /images/sles_base.raw base image with:

> qemu-img create -f qcow2 /images/sles_derived.qcow2 \
-o backing_file=/images/sles_base.raw
Formatting '/images/sles_derived.qcow2', fmt=qcow2 size=4294967296 \
backing_file='/images/sles_base.raw' encryption=off cluster_size=0

Look at the derived image details:

> qemu-img info /images/sles_derived.qcow2
image: /images/sles_derived.qcow2
file format: qcow2
virtual size: 4.0G (4294967296 bytes)
disk size: 140K
cluster_size: 65536
backing file: /images/sles_base.raw \
(actual path: /images/sles_base.raw)

Although the reserved size of the derived image is the same as the size of the base image (4 GB), the actual size is 140 KB only. The reason is that only changes made to the system inside the derived image are saved. Run the derived virtual machine, register it, if needed, and apply the latest patches. Do any other changes in the system such as removing unneeded or installing new software packages. Then shut the VM Guest down and examine its details once more:

> qemu-img info /images/sles_derived.qcow2
image: /images/sles_derived.qcow2
file format: qcow2
virtual size: 4.0G (4294967296 bytes)
disk size: 1.1G
cluster_size: 65536
backing file: /images/sles_base.raw \
(actual path: /images/sles_base.raw)

The disk size value has grown to 1.1 GB, which is the disk space occupied by the changes on the file system compared to the base image.

31.2.4.3 Rebasing Derived Images #

After you have modified the derived image (applied patches, installed specific applications, changed environment settings, etc.), it reaches the desired state. At that point, you can merge the original base image and the derived image to create a new base image.

Your original base image (/images/sles_base.raw) holds a freshly installed system. It can be a template for new modified base images, while the new one can contain the same system as the first one plus all security and update patches applied, for example. After you have created this new base image, you can use it as a template for more specialized derived images as well. The new base image becomes independent of the original one. The process of creating base images from derived ones is called rebasing:

> qemu-img convert /images/sles_derived.qcow2 \
-O raw /images/sles_base2.raw

This command created the new base image /images/sles_base2.raw using the raw format.

> qemu-img info /images/sles_base2.raw
image: /images/sles11_base2.raw
file format: raw
virtual size: 4.0G (4294967296 bytes)
disk size: 2.8G

The new image is 0.4 gigabytes bigger than the original base image. It uses no backing file, and you can easily create new derived images based upon it. This lets you create a sophisticated hierarchy of virtual disk images for your organization, saving a lot of time and work.

31.2.4.4 Mounting an Image on a VM Host Server #

It can be useful to mount a virtual disk image under the host system. It is strongly recommended to read Chapter 18, libguestfs and use dedicated tools to access a virtual machine image. However, if you need to do this manually, follow this guide.

Linux systems can mount an internal partition of a raw disk image using a loopback device. The first example procedure is more complex but more illustrative, while the second one is straightforward:

Procedure 31.1: Mounting Disk Image by Calculating Partition Offset #

Set a loop device on the disk image whose partition you want to mount.
```
> losetup /dev/loop0 /images/sles_base.raw
```

Find the sector size and the starting sector number of the partition you want to mount.

> fdisk -lu /dev/loop0

Disk /dev/loop0: 4294 MB, 4294967296 bytes
255 heads, 63 sectors/track, 522 cylinders, total 8388608 sectors
Units = sectors of 1 * 512 = 5121 bytes
Disk identifier: 0x000ceca8

       Device Boot      Start         End      Blocks   Id  System
/dev/loop0p1              63     1542239      771088+  82  Linux swap
/dev/loop0p2   *     15422402    8385929     3421845   83  Linux

1	The disk sector size.
2	The starting sector of the partition.

Calculate the partition start offset:
sector_size * sector_start = 512 * 1542240 = 789626880

Delete the loop and mount the partition inside the disk image with the calculated offset on a prepared directory.

> losetup -d /dev/loop0
> mount -o loop,offset=789626880 \
/images/sles_base.raw /mnt/sles/
> ls -l /mnt/sles/
total 112
drwxr-xr-x   2 root root  4096 Nov 16 10:02 bin
drwxr-xr-x   3 root root  4096 Nov 16 10:27 boot
drwxr-xr-x   5 root root  4096 Nov 16 09:11 dev
[...]
drwxrwxrwt  14 root root  4096 Nov 24 09:50 tmp
drwxr-xr-x  12 root root  4096 Nov 16 09:16 usr
drwxr-xr-x  15 root root  4096 Nov 16 09:22 var

Copy one or more files onto the mounted partition and unmount it when finished.

> cp /etc/X11/xorg.conf /mnt/sles/root/tmp
> ls -l /mnt/sles/root/tmp
> umount /mnt/sles/

Warning: Do not Write to Images Currently in Use

Never mount a partition of an image of a running virtual machine in a read-write mode. This could corrupt the partition and break the whole VM Guest.

31 Guest Installation #

31.1 Basic Installation with qemu-system-ARCH #

31.2 Managing Disk Images with qemu-img #

31.2.1 General Information on qemu-img Invocation #

31.2.2 Creating, Converting and Checking Disk Images #

31.2.2.1 qemu-img create #

31.2.2.2 qemu-img convert #

31.2.2.3 qemu-img check #

31.2.2.4 Increasing the Size of an Existing Disk Image #

31.2.2.5 Advanced Options for the qcow2 File Format #

31.2.2.5.1 Choosing the Right Cache Size #

31.2.2.5.2 Configuring the Cache Size #

31.2.2.5.3 Reducing the Memory Usage #

31.2.3 Managing Snapshots of Virtual Machines with qemu-img #

31.2.3.1 Listing Existing Snapshots #

31.2.3.2 Creating Snapshots of a Powered-Off Virtual Machine #

31.2.3.3 Deleting Snapshots #

31.2.4 Manipulate Disk Images Effectively #

31.2.4.1 Base and Derived Images #

31.2.4.2 Creating Derived Images #

31.2.4.3 Rebasing Derived Images #

31.2.4.4 Mounting an Image on a VM Host Server #

31.1 Basic Installation with `qemu-system-ARCH` #

31.2 Managing Disk Images with `qemu-img` #