X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=qemu-img.texi;h=00fca8da865d6adb701fecc4d52831aca0385620;hb=89eb147c2cfd2c797d3662aa2f55254441f0595a;hp=526474c112f0761b7e8eef2ad6ba2bbf3fcdb470;hpb=de20fbcac9d71fc91635919bfbe0883a7df71887;p=mirror_qemu.git diff --git a/qemu-img.texi b/qemu-img.texi index 526474c112..00fca8da86 100644 --- a/qemu-img.texi +++ b/qemu-img.texi @@ -4,6 +4,16 @@ usage: qemu-img command [command options] @c man end @end example +@c man begin DESCRIPTION +qemu-img allows you to create, convert and modify images offline. It can handle +all image formats supported by QEMU. + +@b{Warning:} Never use qemu-img to modify images in use by a running virtual +machine or any other process; this may destroy the image. Also, be aware that +querying an image that is being modified by another process may encounter +inconsistent state. +@c man end + @c man begin OPTIONS The following commands are supported: @@ -18,6 +28,10 @@ Command parameters: is the disk image format. It is guessed automatically in most cases. See below for a description of the supported disk formats. +@item --backing-chain +will enumerate information about backing files in a disk image chain. Refer +below for further description. + @item size is the disk image size in bytes. Optional suffixes @code{k} or @code{K} (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M) @@ -38,6 +52,17 @@ by the used format or see the format descriptions below for details. indicates that target image must be compressed (qcow format only) @item -h with or without a command shows help and lists the supported formats +@item -p +display progress bar (convert and rebase commands only) +@item -S @var{size} +indicates the consecutive number of bytes that must contain only zeros +for qemu-img to create a sparse image during conversion. This value is rounded +down to the nearest 512 bytes. You may use the common size suffixes like +@code{k} for kilobytes. +@item -t @var{cache} +specifies the cache mode that should be used with the (destination) file. See +the documentation of the emulator's @code{-drive cache=...} option for allowed +values. @end table Parameters to snapshot subcommand: @@ -59,10 +84,15 @@ lists all snapshots in the given image Command description: @table @option -@item check [-f @var{fmt}] @var{filename} +@item check [-f @var{fmt}] [-r [leaks | all]] @var{filename} Perform a consistency check on the disk image @var{filename}. +If @code{-r} is specified, qemu-img tries to repair any inconsistencies found +during the check. @code{-r leaks} repairs only cluster leaks, whereas +@code{-r all} fixes all kinds of errors, with a higher risk of choosing the +wrong fix or hiding corruption that has already occurred. + Only the formats @code{qcow2}, @code{qed} and @code{vdi} support consistency checks. @@ -80,11 +110,11 @@ this case. @var{backing_file} will never be modified unless you use the The size can also be specified using the @var{size} option with @code{-o}, it doesn't need to be specified separately in this case. -@item commit [-f @var{fmt}] @var{filename} +@item commit [-f @var{fmt}] [-t @var{cache}] @var{filename} Commit the changes recorded in @var{filename} in its base image. -@item convert [-c] [-f @var{fmt}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_name}] @var{filename} [@var{filename2} [...]] @var{output_filename} +@item convert [-c] [-p] [-f @var{fmt}] [-t @var{cache}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_name}] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename} Convert the disk image @var{filename} or a snapshot @var{snapshot_name} to disk image @var{output_filename} using format @var{output_fmt}. It can be optionally compressed (@code{-c} @@ -103,25 +133,43 @@ created as a copy on write image of the specified base image; the @var{backing_file} should have the same content as the input's base image, however the path, image format, etc may differ. -@item info [-f @var{fmt}] @var{filename} +@item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename} Give information about the disk image @var{filename}. Use it in particular to know the size reserved on disk which can be different from the displayed size. If VM snapshots are stored in the disk image, -they are displayed too. +they are displayed too. The command can output in the format @var{ofmt} +which is either @code{human} or @code{json}. + +If a disk image has a backing file chain, information about each disk image in +the chain can be recursively enumerated by using the option @code{--backing-chain}. + +For instance, if you have an image chain like: + +@example +base.qcow2 <- snap1.qcow2 <- snap2.qcow2 +@end example + +To enumerate information about each disk image in the above chain, starting from top to base, do: + +@example +qemu-img info --backing-chain snap2.qcow2 +@end example @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename} List, apply, create or delete snapshots in image @var{filename}. -@item rebase [-f @var{fmt}] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename} +@item rebase [-f @var{fmt}] [-t @var{cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename} Changes the backing file of an image. Only the formats @code{qcow2} and @code{qed} support changing the backing file. The backing file is changed to @var{backing_file} and (if the image format of @var{filename} supports this) the backing file format is changed to -@var{backing_fmt}. +@var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty +string), then the image is rebased onto no backing file (i.e. it will exist +independently of any backing file). There are two different modes in which @code{rebase} can operate: @table @option @@ -148,6 +196,24 @@ It can be used without an accessible old backing file, i.e. you can use it to fix an image whose backing file has already been moved/renamed. @end table +You can use @code{rebase} to perform a ``diff'' operation on two +disk images. This can be useful when you have copied or cloned +a guest, and you want to get back to a thin image on top of a +template or base image. + +Say that @code{base.img} has been cloned as @code{modified.img} by +copying it, and that the @code{modified.img} guest has run so there +are now some changes compared to @code{base.img}. To construct a thin +image called @code{diff.qcow2} that contains just the differences, do: + +@example +qemu-img create -f qcow2 -b modified.img diff.qcow2 +qemu-img rebase -b base.img diff.qcow2 +@end example + +At this point, @code{modified.img} can be discarded, since +@code{base.img + diff.qcow2} contains the same information. + @item resize @var{filename} [+ | -]@var{size} Change the disk image as if it had been created with @var{size}. @@ -160,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 @@ -181,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 @@ -201,50 +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. +This option can only be enabled if @code{compat=1.1} is specified. -@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. +@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_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