Commit d3067b02 authored by Kevin Wolf's avatar Kevin Wolf
Browse files

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: default avatarKevin Wolf <kwolf@redhat.com>
Acked-by: default avatarStefan Hajnoczi <stefanha@redhat.com>
parent a13e5e05

qemu-doc.texi

+167 −0
Original line number Diff line number Diff line
@@ -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

qemu-img.texi

+27 −57
Original line number Diff line number Diff line
@@ -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

@c man end



@ignore

@c man begin NOTES

Supported image file formats:



@table @option
@@ -247,6 +250,13 @@ 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
@@ -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.



@end table

@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.



@item 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:

@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. Left for compatibility.

@item 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:

@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.

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



@ignore



@setfilename qemu-img

@settitle QEMU disk image utility