From d3067b020bdeb572f381c5be4420eedfd6af5884 Mon Sep 17 00:00:00 2001 From: Kevin Wolf Date: Wed, 21 Nov 2012 14:21:47 +0100 Subject: 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 Acked-by: Stefan Hajnoczi --- qemu-doc.texi | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) (limited to 'qemu-doc.texi') diff --git a/qemu-doc.texi b/qemu-doc.texi index 6ff309ddf4..6d7f50d832 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -416,6 +416,7 @@ snapshots. * vm_snapshots:: VM snapshots * qemu_img_invocation:: qemu-img Invocation * qemu_nbd_invocation:: qemu-nbd Invocation +* disk_images_formats:: Disk image file formats * host_drives:: Using host drives * disk_images_fat_images:: Virtual FAT disk images * disk_images_nbd:: NBD access @@ -507,6 +508,172 @@ state is not saved or restored properly (in particular USB). @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 @subsection Using host drives -- cgit v1.2.1