openkylin
/
qemu
mirror of https://gitee.com/openkylin/qemu.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

Documentation: Update image format information 

Document new and yet undocumented options and image formats. The
qemu-img man page contains information only for raw and qcow2 now and
references the HTML documentation for a more detailed description of
other formats.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com>
This commit is contained in:
Kevin Wolf 2012-11-21 14:21:47 +01:00
parent a13e5e0557
commit d3067b020b
2 changed files with 196 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
qemu-doc.texi
View File

@ -416,6 +416,7 @@ snapshots.
* vm_snapshots:: VM snapshots * vm_snapshots:: VM snapshots
* qemu_img_invocation:: qemu-img Invocation * qemu_img_invocation:: qemu-img Invocation
* qemu_nbd_invocation:: qemu-nbd Invocation * qemu_nbd_invocation:: qemu-nbd Invocation
* disk_images_formats:: Disk image file formats
* host_drives:: Using host drives * host_drives:: Using host drives
* disk_images_fat_images:: Virtual FAT disk images * disk_images_fat_images:: Virtual FAT disk images
* disk_images_nbd:: NBD access * disk_images_nbd:: NBD access
@ -507,6 +508,172 @@ state is not saved or restored properly (in particular USB).
@include qemu-nbd.texi @include qemu-nbd.texi
@node disk_images_formats
@subsection Disk image file formats
QEMU supports many image file formats that can be used with VMs as well as with
any of the tools (like @code{qemu-img}). This includes the preferred formats
raw and qcow2 as well as formats that are supported for compatibility with
older QEMU versions or other hypervisors.
Depending on the image format, different options can be passed to
@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.
This section describes each format and the options that are supported for it.
@table @option
@item raw
Raw disk image format. This format has the advantage of
being simple and easily exportable to all other emulators. If your
file system supports @emph{holes} (for example in ext2 or ext3 on
Linux or NTFS on Windows), then only the written sectors will reserve
space. Use @code{qemu-img info} to know the real size used by the
image or @code{ls -ls} on Unix/Linux.
@item qcow2
QEMU image format, the most versatile format. Use it to have smaller
images (useful if your filesystem does not supports holes, for example
on Windows), optional AES encryption, zlib based compression and
support of multiple VM snapshots.
Supported options:
@table @code
@item compat
Determines the qcow2 version to use. @code{compat=0.10} uses the traditional
image format that can be read by any QEMU since 0.10 (this is the default).
@code{compat=1.1} enables image format extensions that only QEMU 1.1 and
newer understand. Amongst others, this includes zero clusters, which allow
efficient copy-on-read for sparse images.
@item backing_file
File name of a base image (see @option{create} subcommand)
@item backing_fmt
Image format of the base image
@item encryption
If this option is set to @code{on}, the image is encrypted.
Encryption uses the AES format which is very secure (128 bit keys). Use
a long password (16 characters) to get maximum protection.
@item cluster_size
Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
sizes can improve the image file size whereas larger cluster sizes generally
provide better performance.
@item preallocation
Preallocation mode (allowed values: off, metadata). An image with preallocated
metadata is initially larger but can improve performance when the image needs
to grow.
@item lazy_refcounts
If this option is set to @code{on}, reference count updates are postponed with
the goal of avoiding metadata I/O and improving performance. This is
particularly interesting with @option{cache=writethrough} which doesn't batch
metadata updates. The tradeoff is that after a host crash, the reference count
tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
check -r all} is required, which may take some time.
This option can only be enabled if @code{compat=1.1} is specified.
@end table
@item qed
Old QEMU image format with support for backing files and compact image files
(when your filesystem or transport medium does not support holes).
When converting QED images to qcow2, you might want to consider using the
@code{lazy_refcounts=on} option to get a more QED-like behaviour.
Supported options:
@table @code
@item backing_file
File name of a base image (see @option{create} subcommand).
@item backing_fmt
Image file format of backing file (optional). Useful if the format cannot be
autodetected because it has no header, like some vhd/vpc files.
@item cluster_size
Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
cluster sizes can improve the image file size whereas larger cluster sizes
generally provide better performance.
@item table_size
Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
and 16). There is normally no need to change this value but this option can be
used for performance benchmarking.
@end table
@item qcow
Old QEMU image format with support for backing files, compact image files,
encryption and compression.
Supported options:
@table @code
@item backing_file
File name of a base image (see @option{create} subcommand)
@item encryption
If this option is set to @code{on}, the image is encrypted.
@end table
@item cow
User Mode Linux Copy On Write image format. It is supported only for
compatibility with previous versions.
Supported options:
@table @code
@item backing_file
File name of a base image (see @option{create} subcommand)
@end table
@item vdi
VirtualBox 1.1 compatible image format.
Supported options:
@table @code
@item static
If this option is set to @code{on}, the image is created with metadata
preallocation.
@end table
@item vmdk
VMware 3 and 4 compatible image format.
Supported options:
@table @code
@item backing_file
File name of a base image (see @option{create} subcommand).
@item compat6
Create a VMDK version 6 image (instead of version 4)
@item subformat
Specifies which VMDK subformat to use. Valid options are
@code{monolithicSparse} (default),
@code{monolithicFlat},
@code{twoGbMaxExtentSparse},
@code{twoGbMaxExtentFlat} and
@code{streamOptimized}.
@end table
@item vpc
VirtualPC compatible image format (VHD).
Supported options:
@table @code
@item subformat
Specifies which VHD subformat to use. Valid options are
@code{dynamic} (default) and @code{fixed}.
@end table
@end table
@subsubsection Read-only formats
More disk image file formats are supported in a read-only mode.
@table @option
@item bochs
Bochs images of @code{growing} type.
@item cloop
Linux Compressed Loop image, useful only to reuse directly compressed
CD-ROM images present for example in the Knoppix CD-ROMs.
@item dmg
Apple disk image.
@item parallels
Parallels disk image format.
@end table
@node host_drives @node host_drives
@subsection Using host drives @subsection Using host drives

88
qemu-img.texi
View File

@ -226,7 +226,10 @@ After using this command to grow a disk image, you must use file system and
partitioning tools inside the VM to actually begin using the new space on the partitioning tools inside the VM to actually begin using the new space on the
device. device.
@end table @end table
@c man end
@ignore
@c man begin NOTES
Supported image file formats: Supported image file formats:
@table @option @table @option
@ -247,6 +250,13 @@ support of multiple VM snapshots.
Supported options: Supported options:
@table @code @table @code
@item compat
Determines the qcow2 version to use. @code{compat=0.10} uses the traditional
image format that can be read by any QEMU since 0.10 (this is the default).
@code{compat=1.1} enables image format extensions that only QEMU 1.1 and
newer understand. Amongst others, this includes zero clusters, which allow
efficient copy-on-read for sparse images.
@item backing_file @item backing_file
File name of a base image (see @option{create} subcommand) File name of a base image (see @option{create} subcommand)
@item backing_fmt @item backing_fmt
@ -267,73 +277,33 @@ Preallocation mode (allowed values: off, metadata). An image with preallocated
metadata is initially larger but can improve performance when the image needs metadata is initially larger but can improve performance when the image needs
to grow. to grow.
@item lazy_refcounts
If this option is set to @code{on}, reference count updates are postponed with
the goal of avoiding metadata I/O and improving performance. This is
particularly interesting with @option{cache=writethrough} which doesn't batch
metadata updates. The tradeoff is that after a host crash, the reference count
tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
check -r all} is required, which may take some time.
This option can only be enabled if @code{compat=1.1} is specified.
@end table @end table
@item qed @item Other
Image format with support for backing files and compact image files (when your QEMU also supports various other image file formats for compatibility with
filesystem or transport medium does not support holes). Good performance due older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), qcow1
to less metadata than the more featureful qcow2 format, especially with and QED. For a full list of supported formats see @code{qemu-img --help}.
cache=writethrough or cache=directsync. Consider using qcow2 which will soon For a more detailed description of these formats, see the QEMU Emulation User
have a similar optimization and is most actively developed. Documentation.
Supported options: The main purpose of the block drivers for these formats is image conversion.
@table @code For running VMs, it is recommended to convert the disk images to either raw or
@item backing_file qcow2 in order to achieve good performance.
File name of a base image (see @option{create} subcommand).
@item backing_fmt
Image file format of backing file (optional). Useful if the format cannot be
autodetected because it has no header, like some vhd/vpc files.
@item cluster_size
Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
cluster sizes can improve the image file size whereas larger cluster sizes
generally provide better performance.
@item table_size
Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
and 16). There is normally no need to change this value but this option can be
used for performance benchmarking.
@end table
@item qcow
Old QEMU image format. Left for compatibility.
Supported options:
@table @code
@item backing_file
File name of a base image (see @option{create} subcommand)
@item encryption
If this option is set to @code{on}, the image is encrypted.
@end table
@item cow
User Mode Linux Copy On Write image format. Used to be the only growable
image format in QEMU. It is supported only for compatibility with
previous versions. It does not work on win32.
@item vdi
VirtualBox 1.1 compatible image format.
@item vmdk
VMware 3 and 4 compatible image format.
Supported options:
@table @code
@item backing_fmt
Image format of the base image
@item compat6
Create a VMDK version 6 image (instead of version 4)
@end table
@item vpc
VirtualPC compatible image format (VHD).
@item cloop
Linux Compressed Loop image, useful only to reuse directly compressed
CD-ROM images present for example in the Knoppix CD-ROMs.
@end table @end table
@c man end @c man end
@ignore
@setfilename qemu-img @setfilename qemu-img
@settitle QEMU disk image utility @settitle QEMU disk image utility