[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH 1.3 v3 2/2] Documentation: Update image format infor
From: |
Kevin Wolf |
Subject: |
[Qemu-devel] [PATCH 1.3 v3 2/2] Documentation: Update image format information |
Date: |
Mon, 26 Nov 2012 14:21:49 +0100 |
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 <address@hidden>
---
qemu-doc.texi | 167 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
qemu-img.texi | 84 +++++++++-------------------
2 files changed, 194 insertions(+), 57 deletions(-)
diff --git a/qemu-doc.texi b/qemu-doc.texi
index 6ff309d..cf62843 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
address@hidden disk_images_formats
address@hidden 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
address@hidden create} and @code{qemu-img convert} using the @code{-o} option.
+This section describes each format and the options that are supported for it.
+
address@hidden @option
address@hidden 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.
+
address@hidden 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:
address@hidden @code
address@hidden 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).
address@hidden 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.
+
address@hidden backing_file
+File name of a base image (see @option{create} subcommand)
address@hidden backing_fmt
+Image format of the base image
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden table
+
address@hidden 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
address@hidden option to get a more QED-like behaviour.
+
+Supported options:
address@hidden @code
address@hidden backing_file
+File name of a base image (see @option{create} subcommand).
address@hidden 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.
address@hidden 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.
address@hidden 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.
address@hidden table
+
address@hidden qcow
+Old QEMU image format with support for backing files, compact image files,
+encryption and compression.
+
+Supported options:
address@hidden @code
address@hidden backing_file
+File name of a base image (see @option{create} subcommand)
address@hidden encryption
+If this option is set to @code{on}, the image is encrypted.
address@hidden table
+
address@hidden cow
+User Mode Linux Copy On Write image format. It is supported only for
+compatibility with previous versions.
+Supported options:
address@hidden @code
address@hidden backing_file
+File name of a base image (see @option{create} subcommand)
address@hidden table
+
address@hidden vdi
+VirtualBox 1.1 compatible image format.
+Supported options:
address@hidden @code
address@hidden static
+If this option is set to @code{on}, the image is created with metadata
+preallocation.
address@hidden table
+
address@hidden vmdk
+VMware 3 and 4 compatible image format.
+
+Supported options:
address@hidden @code
address@hidden backing_file
+File name of a base image (see @option{create} subcommand).
address@hidden compat6
+Create a VMDK version 6 image (instead of version 4)
address@hidden subformat
+Specifies which VMDK subformat to use. Valid options are
address@hidden (default),
address@hidden,
address@hidden,
address@hidden and
address@hidden
address@hidden table
+
address@hidden vpc
+VirtualPC compatible image format (VHD).
+Supported options:
address@hidden @code
address@hidden subformat
+Specifies which VHD subformat to use. Valid options are
address@hidden (default) and @code{fixed}.
address@hidden table
address@hidden table
+
address@hidden Read-only formats
+More disk image file formats are supported in a read-only mode.
address@hidden @option
address@hidden bochs
+Bochs images of @code{growing} type.
address@hidden cloop
+Linux Compressed Loop image, useful only to reuse directly compressed
+CD-ROM images present for example in the Knoppix CD-ROMs.
address@hidden dmg
+Apple disk image.
address@hidden parallels
+Parallels disk image format.
address@hidden table
+
+
@node host_drives
@subsection Using host drives
diff --git a/qemu-img.texi b/qemu-img.texi
index 60b83fc..00fca8d 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -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
device.
@end table
address@hidden man end
address@hidden
address@hidden man begin NOTES
Supported image file formats:
@table @option
@@ -247,6 +250,13 @@ support of multiple VM snapshots.
Supported options:
@table @code
address@hidden 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).
address@hidden 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
@@ -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
to grow.
address@hidden table
address@hidden 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.
address@hidden qed
-Image format with support for backing files and compact image files (when your
-filesystem or transport medium does not support holes). Good performance due
-to less metadata than the more featureful qcow2 format, especially with
-cache=writethrough or cache=directsync. Consider using qcow2 which will soon
-have a similar optimization and is most actively developed.
+This option can only be enabled if @code{compat=1.1} is specified.
-Supported options:
address@hidden @code
address@hidden backing_file
-File name of a base image (see @option{create} subcommand).
address@hidden 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.
address@hidden 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.
address@hidden 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
address@hidden qcow
-Old QEMU image format. Left for compatibility.
address@hidden Other
+QEMU also supports various other image file formats for compatibility with
+older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), qcow1
+and QED. For a full list of supported formats see @code{qemu-img --help}.
+For a more detailed description of these formats, see the QEMU Emulation User
+Documentation.
-Supported options:
address@hidden @code
address@hidden backing_file
-File name of a base image (see @option{create} subcommand)
address@hidden encryption
-If this option is set to @code{on}, the image is encrypted.
address@hidden table
-
address@hidden 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.
address@hidden vdi
-VirtualBox 1.1 compatible image format.
address@hidden vmdk
-VMware 3 and 4 compatible image format.
-
-Supported options:
address@hidden @code
address@hidden backing_fmt
-Image format of the base image
address@hidden compat6
-Create a VMDK version 6 image (instead of version 4)
address@hidden table
-
address@hidden vpc
-VirtualPC compatible image format (VHD).
-
address@hidden cloop
-Linux Compressed Loop image, useful only to reuse directly compressed
-CD-ROM images present for example in the Knoppix CD-ROMs.
+The main purpose of the block drivers for these formats is image conversion.
+For running VMs, it is recommended to convert the disk images to either raw or
+qcow2 in order to achieve good performance.
@end table
@c man end
address@hidden
-
@setfilename qemu-img
@settitle QEMU disk image utility
--
1.7.6.5