Chapter 10. QEMU-img and QEMU Guest Agent
/usr/share/doc/qemu-*/README.systemtap
.
10.1. Using qemu-img
qemu-img
command line tool is used for formatting, modifying and verifying various file systems used by KVM. qemu-img
options and usages are listed below.
Perform a consistency check on the disk image filename.
# qemu-img check -f qcow2 --output=qcow2 -r all filename-img.qcow2
Note
qcow2
and vdi
formats support consistency checks.
-r
tries to repair any inconsistencies that are found during the check, but when used with -r leaks
cluster leaks are repaired and when used with -r all
all kinds of errors are fixed. Note that this has a risk of choosing the wrong fix or hiding corruption issues that may have already occurred.
Commits any changes recorded in the specified file (filename) to the file's base image with the qemu-img commit
command. Optionally, specify the file's format type (format).
# qemu-img commit [-fformat
] [-tcache
] filename
The convert
option is used to convert one recognized image format to another image format.
# qemu-img convert [-c] [-p] [-fformat
] [-tcache
] [-Ooutput_format
] [-ooptions
] [-Ssparse_size
] filename output_filename
-p
parameter shows the progress of the command (optional and not for every command) and -S
option allows for the creation of a sparse file, which is included within the disk image. Sparse files in all purposes function like a standard file, except that the physical blocks that only contain zeros (nothing). When the Operating System sees this file, it treats it as it exists and takes up actual disk space, even though in reality it does not take any. This is particularly helpful when creating a disk for a guest virtual machine as this gives the appearance that the disk has taken much more disk space than it has. For example, if you set -S to 50Gb on a disk image that is 10Gb, then your 10Gb of disk space will appear to be 60Gb in size even though only 10Gb is actually being used.
filename
to disk image output_filename
using format output_format
. The disk image can be optionally compressed with the -c
option, or encrypted with the -o
option by setting -o encryption
. Note that the options available with the -o
parameter differ with the selected format.
qcow2
format supports encryption or compression. qcow2
encryption uses the AES format with secure 128-bit keys. qcow2
compression is read-only, so if a compressed sector is converted from qcow2
format, it is written to the new format as uncompressed data.
qcow
or cow
. The empty sectors are detected and suppressed from the destination image.
Create the new disk image filename of size size
and format format
.
# qemu-img create [-fformat
] [-o options] filename [size
][preallocation
]
-o backing_file=filename
, the image will only record differences between itself and the base image. The backing file will not be modified unless you use the commit
command. No size needs to be specified in this case.
-o preallocation=off|meta|full|falloc
. Images with preallocated metadata are larger than images without. However in cases where the image size increases, performance will improve as the image grows.
full
allocation can take a long time with large images. In cases where you want full allocation and time is of the essence, using falloc
will save you time.
The info
parameter displays information about a disk image filename. The format for the info
option is as follows:
# qemu-img info [-f format] filename
qcow2
image on a block device. This is done by running the qemu-img
. You can check that the image in use is the one that matches the output of the qemu-img info
command with the qemu-img check
command. Refer to Section 10.1, “Using qemu-img”.
# qemu-img info /dev/vg-90.100-sluo/lv-90-100-sluo image: /dev/vg-90.100-sluo/lv-90-100-sluo file format: qcow2 virtual size: 20G (21474836480 bytes) disk size: 0 cluster_size: 65536
The # qemu-img map [-f format] [--output=output_format] filename
command dumps the metadata of the image filename and its backing file chain. Specifically, this command dumps the allocation state of every sector of a specified file, together with the topmost file that allocates it in the backing file chain. For example, if you have a chain such as c.qcow2 -f
format option is the format of the specified image file. Formats such as raw, qcow2, vhdx and vmdk may be used. There are two output options possible: human
and json
.
human
is the default setting. It is designed to be more readable to the human eye, and as such, this format should not be parsed. For clarity and simplicity, the defaulthuman
format only dumps known-nonzero areas of the file. Known-zero parts of the file are omitted altogether, and likewise for parts that are not allocated throughout the chain. When the command is executed, qemu-img output will identify a file from where the data can be read, and the offset in the file. The output is displayed as a table with four columns; the first three of which are hexadecimal numbers.# qemu-img map -f qcow2 --output=human /tmp/test.qcow2 Offset Length Mapped to File 0 0x20000 0x50000 /tmp/test.qcow2 0x100000 0x80000 0x70000 /tmp/test.qcow2 0x200000 0x1f0000 0xf0000 /tmp/test.qcow2 0x3c00000 0x20000 0x2e0000 /tmp/test.qcow2 0x3fd0000 0x10000 0x300000 /tmp/test.qcow2
json
, or JSON (JavaScript Object Notation), is readable by humans, but as it is a programming language, it is also designed to be parsed. For example, if you want to parse the output of "qemu-img map" in a parser then you should use the option--output=json
.# qemu-img map -f qcow2 --output=json /tmp/test.qcow2 [{ "start": 0, "length": 131072, "depth": 0, "zero": false, "data": true, "offset": 327680}, { "start": 131072, "length": 917504, "depth": 0, "zero": true, "data": false},
For more information on the JSON format, refer to the qemu-img(1) man page.
Changes the backing file of an image.
# qemu-img rebase [-f format] [-t cache] [-p] [-u] -b backing_file [-F backing_format] filename
Note
qcow2
format supports changing the backing file (rebase).
qemu-img rebase
command will take care of keeping the guest virtual machine-visible content of filename unchanged. In order to achieve this, any clusters that differ between backing_file and old backing file of filename are merged into filename before making any changes to the backing file.
qemu-img rebase
. In this mode, only the backing file name and format of filename is changed, without any checks taking place on the file contents. Make sure the new backing file is specified correctly or the guest-visible content of the image will be corrupted.
Change the disk image filename as if it had been created with size size. Only images in raw format can be resized regardless of version. Red Hat Enterprise Linux 6.1 and later adds the ability to grow (but not shrink) images in qcow2
format.
# qemu-img resize filename size
+
to grow, or -
to reduce the size of the disk image by that number of bytes. Adding a unit suffix allows you to set the image size in kilobytes (K), megabytes (M), gigabytes (G) or terabytes (T).
# qemu-img resize filename [+|-]size[K|M|G|T]
Warning
List, apply, create, or delete an existing snapshot (snapshot) of an image (filename).
# qemu-img snapshot [ -l | -a snapshot | -c snapshot | -d snapshot ] filename
-l
lists all snapshots associated with the specified disk image. The apply option, -a
, reverts the disk image (filename) to the state of a previously saved snapshot. -c
creates a snapshot (snapshot) of an image (filename). -d
deletes the specified snapshot.
qemu-img is designed to convert files to one of the following formats:
-
raw
- Raw disk image format (default). This can be the fastest file-based format. If your file system supports holes (for example in ext2 or ext3 on Linux or NTFS on Windows), then only the written sectors will reserve space. Use
qemu-img info
to obtain the real size used by the image orls -ls
on Unix/Linux. Although Raw images give optimal performance, only very basic features are available with a Raw image (for example, no snapshots are available). -
qcow2
- QEMU image format, the most versatile format with the best feature set. Use it to have optional AES encryption, zlib-based compression, support of multiple VM snapshots, and smaller images, which are useful on file systems that do not support holes (non-NTFS file systems on Windows). Note that this expansive feature set comes at the cost of performance.
raw
or qcow2
format. The format of an image is usually detected automatically. In addition to converting these formats into raw
or qcow2
, they can be converted back from raw
or qcow2
to the original format.
bochs
- Bochs disk image format.
cloop
- Linux Compressed Loop image, useful only to reuse directly compressed CD-ROM images present for example in the Knoppix CD-ROMs.
cow
- User Mode Linux Copy On Write image format. The
cow
format is included only for compatibility with previous versions. It does not work with Windows. dmg
- Mac disk image format.
nbd
- Network block device.
parallels
- Parallels virtualization disk image format.
qcow
- Old QEMU image format. Only included for compatibility with older versions.
vdi
- Oracle VM VirtualBox hard disk image format.
vmdk
- VMware compatible image format (read-write support for versions 1 and 2, and read-only support for version 3).
vpc
- Windows Virtual PC disk image format. Also referred to as
vhd
, or Microsoft virtual hard disk image format. vvfat
- Virtual VFAT disk image format.