Merge remote-tracking branch 'remotes/jasowang/tags/net-pull-request' into staging
[qemu.git] / docs / tools / qemu-img.rst
1 QEMU disk image utility
2 =======================
3
4 Synopsis
5 --------
6
7 **qemu-img** [*standard options*] *command* [*command options*]
8
9 Description
10 -----------
11
12 qemu-img allows you to create, convert and modify images offline. It can handle
13 all image formats supported by QEMU.
14
15 **Warning:** Never use qemu-img to modify images in use by a running virtual
16 machine or any other process; this may destroy the image. Also, be aware that
17 querying an image that is being modified by another process may encounter
18 inconsistent state.
19
20 Options
21 -------
22
23 .. program:: qemu-img
24
25 Standard options:
26
27 .. option:: -h, --help
28
29   Display this help and exit
30
31 .. option:: -V, --version
32
33   Display version information and exit
34
35 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
36
37   .. include:: ../qemu-option-trace.rst.inc
38
39 The following commands are supported:
40
41 .. hxtool-doc:: qemu-img-cmds.hx
42
43 Command parameters:
44
45 *FILENAME* is a disk image filename.
46
47 *FMT* is the disk image format. It is guessed automatically in most
48 cases. See below for a description of the supported disk formats.
49
50 *SIZE* is the disk image size in bytes. Optional suffixes ``k`` or
51 ``K`` (kilobyte, 1024) ``M`` (megabyte, 1024k) and ``G`` (gigabyte,
52 1024M) and T (terabyte, 1024G) are supported.  ``b`` is ignored.
53
54 *OUTPUT_FILENAME* is the destination disk image filename.
55
56 *OUTPUT_FMT* is the destination format.
57
58 *OPTIONS* is a comma separated list of format specific options in a
59 name=value format. Use ``-o ?`` for an overview of the options supported
60 by the used format or see the format descriptions below for details.
61
62 *SNAPSHOT_PARAM* is param used for internal snapshot, format is
63 'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'.
64
65 ..
66   Note the use of a new 'program'; otherwise Sphinx complains about
67   the -h option appearing both in the above option list and this one.
68
69 .. program:: qemu-img-common-opts
70
71 .. option:: --object OBJECTDEF
72
73   is a QEMU user creatable object definition. See the :manpage:`qemu(1)`
74   manual page for a description of the object properties. The most common
75   object type is a ``secret``, which is used to supply passwords and/or
76   encryption keys.
77
78 .. option:: --image-opts
79
80   Indicates that the source *FILENAME* parameter is to be interpreted as a
81   full option string, not a plain filename. This parameter is mutually
82   exclusive with the *-f* parameter.
83
84 .. option:: --target-image-opts
85
86   Indicates that the OUTPUT_FILENAME parameter(s) are to be interpreted as
87   a full option string, not a plain filename. This parameter is mutually
88   exclusive with the *-O* parameters. It is currently required to also use
89   the *-n* parameter to skip image creation. This restriction may be relaxed
90   in a future release.
91
92 .. option:: --force-share (-U)
93
94   If specified, ``qemu-img`` will open the image in shared mode, allowing
95   other QEMU processes to open it in write mode. For example, this can be used to
96   get the image information (with 'info' subcommand) when the image is used by a
97   running guest.  Note that this could produce inconsistent results because of
98   concurrent metadata changes, etc. This option is only allowed when opening
99   images in read-only mode.
100
101 .. option:: --backing-chain
102
103   Will enumerate information about backing files in a disk image chain. Refer
104   below for further description.
105
106 .. option:: -c
107
108   Indicates that target image must be compressed (qcow format only).
109
110 .. option:: -h
111
112   With or without a command, shows help and lists the supported formats.
113
114 .. option:: -p
115
116   Display progress bar (compare, convert and rebase commands only).
117   If the *-p* option is not used for a command that supports it, the
118   progress is reported when the process receives a ``SIGUSR1`` or
119   ``SIGINFO`` signal.
120
121 .. option:: -q
122
123   Quiet mode - do not print any output (except errors). There's no progress bar
124   in case both *-q* and *-p* options are used.
125
126 .. option:: -S SIZE
127
128   Indicates the consecutive number of bytes that must contain only zeros
129   for qemu-img to create a sparse image during conversion. This value is rounded
130   down to the nearest 512 bytes. You may use the common size suffixes like
131   ``k`` for kilobytes.
132
133 .. option:: -t CACHE
134
135   Specifies the cache mode that should be used with the (destination) file. See
136   the documentation of the emulator's ``-drive cache=...`` option for allowed
137   values.
138
139 .. option:: -T SRC_CACHE
140
141   Specifies the cache mode that should be used with the source file(s). See
142   the documentation of the emulator's ``-drive cache=...`` option for allowed
143   values.
144
145 Parameters to compare subcommand:
146
147 .. program:: qemu-img-compare
148
149 .. option:: -f
150
151   First image format
152
153 .. option:: -F
154
155   Second image format
156
157 .. option:: -s
158
159   Strict mode - fail on different image size or sector allocation
160
161 Parameters to convert subcommand:
162
163 .. program:: qemu-img-convert
164
165 .. option:: --bitmaps
166
167   Additionally copy all persistent bitmaps from the top layer of the source
168
169 .. option:: -n
170
171   Skip the creation of the target volume
172
173 .. option:: -m
174
175   Number of parallel coroutines for the convert process
176
177 .. option:: -W
178
179   Allow out-of-order writes to the destination. This option improves performance,
180   but is only recommended for preallocated devices like host devices or other
181   raw block devices.
182
183 .. option:: -C
184
185   Try to use copy offloading to move data from source image to target. This may
186   improve performance if the data is remote, such as with NFS or iSCSI backends,
187   but will not automatically sparsify zero sectors, and may result in a fully
188   allocated target image depending on the host support for getting allocation
189   information.
190
191 .. option:: -r
192
193    Rate limit for the convert process
194
195 .. option:: --salvage
196
197   Try to ignore I/O errors when reading.  Unless in quiet mode (``-q``), errors
198   will still be printed.  Areas that cannot be read from the source will be
199   treated as containing only zeroes.
200
201 .. option:: --target-is-zero
202
203   Assume that reading the destination image will always return
204   zeros. This parameter is mutually exclusive with a destination image
205   that has a backing file. It is required to also use the ``-n``
206   parameter to skip image creation.
207
208 Parameters to dd subcommand:
209
210 .. program:: qemu-img-dd
211
212 .. option:: bs=BLOCK_SIZE
213
214   Defines the block size
215
216 .. option:: count=BLOCKS
217
218   Sets the number of input blocks to copy
219
220 .. option:: if=INPUT
221
222   Sets the input file
223
224 .. option:: of=OUTPUT
225
226   Sets the output file
227
228 .. option:: skip=BLOCKS
229
230   Sets the number of input blocks to skip
231
232 Parameters to snapshot subcommand:
233
234 .. program:: qemu-img-snapshot
235
236 .. option:: snapshot
237
238   Is the name of the snapshot to create, apply or delete
239
240 .. option:: -a
241
242   Applies a snapshot (revert disk to saved state)
243
244 .. option:: -c
245
246   Creates a snapshot
247
248 .. option:: -d
249
250   Deletes a snapshot
251
252 .. option:: -l
253
254   Lists all snapshots in the given image
255
256 Command description:
257
258 .. program:: qemu-img-commands
259
260 .. option:: amend [--object OBJECTDEF] [--image-opts] [-p] [-q] [-f FMT] [-t CACHE] [--force] -o OPTIONS FILENAME
261
262   Amends the image format specific *OPTIONS* for the image file
263   *FILENAME*. Not all file formats support this operation.
264
265   The set of options that can be amended are dependent on the image
266   format, but note that amending the backing chain relationship should
267   instead be performed with ``qemu-img rebase``.
268
269   --force allows some unsafe operations. Currently for -f luks, it allows to
270   erase the last encryption key, and to overwrite an active encryption key.
271
272 .. option:: bench [-c COUNT] [-d DEPTH] [-f FMT] [--flush-interval=FLUSH_INTERVAL] [-i AIO] [-n] [--no-drain] [-o OFFSET] [--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE] [-w] [-U] FILENAME
273
274   Run a simple sequential I/O benchmark on the specified image. If ``-w`` is
275   specified, a write test is performed, otherwise a read test is performed.
276
277   A total number of *COUNT* I/O requests is performed, each *BUFFER_SIZE*
278   bytes in size, and with *DEPTH* requests in parallel. The first request
279   starts at the position given by *OFFSET*, each following request increases
280   the current position by *STEP_SIZE*. If *STEP_SIZE* is not given,
281   *BUFFER_SIZE* is used for its value.
282
283   If *FLUSH_INTERVAL* is specified for a write test, the request queue is
284   drained and a flush is issued before new writes are made whenever the number of
285   remaining requests is a multiple of *FLUSH_INTERVAL*. If additionally
286   ``--no-drain`` is specified, a flush is issued without draining the request
287   queue first.
288
289   if ``-i`` is specified, *AIO* option can be used to specify different
290   AIO backends: ``threads``, ``native`` or ``io_uring``.
291
292   If ``-n`` is specified, the native AIO backend is used if possible. On
293   Linux, this option only works if ``-t none`` or ``-t directsync`` is
294   specified as well.
295
296   For write tests, by default a buffer filled with zeros is written. This can be
297   overridden with a pattern byte specified by *PATTERN*.
298
299 .. option:: bitmap (--merge SOURCE | --add | --remove | --clear | --enable | --disable)... [-b SOURCE_FILE [-F SOURCE_FMT]] [-g GRANULARITY] [--object OBJECTDEF] [--image-opts | -f FMT] FILENAME BITMAP
300
301   Perform one or more modifications of the persistent bitmap *BITMAP*
302   in the disk image *FILENAME*.  The various modifications are:
303
304   ``--add`` to create *BITMAP*, enabled to record future edits.
305
306   ``--remove`` to remove *BITMAP*.
307
308   ``--clear`` to clear *BITMAP*.
309
310   ``--enable`` to change *BITMAP* to start recording future edits.
311
312   ``--disable`` to change *BITMAP* to stop recording future edits.
313
314   ``--merge`` to merge the contents of the *SOURCE* bitmap into *BITMAP*.
315
316   Additional options include ``-g`` which sets a non-default
317   *GRANULARITY* for ``--add``, and ``-b`` and ``-F`` which select an
318   alternative source file for all *SOURCE* bitmaps used by
319   ``--merge``.
320
321   To see what bitmaps are present in an image, use ``qemu-img info``.
322
323 .. option:: check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT] [-r [leaks | all]] [-T SRC_CACHE] [-U] FILENAME
324
325   Perform a consistency check on the disk image *FILENAME*. The command can
326   output in the format *OFMT* which is either ``human`` or ``json``.
327   The JSON output is an object of QAPI type ``ImageCheck``.
328
329   If ``-r`` is specified, qemu-img tries to repair any inconsistencies found
330   during the check. ``-r leaks`` repairs only cluster leaks, whereas
331   ``-r all`` fixes all kinds of errors, with a higher risk of choosing the
332   wrong fix or hiding corruption that has already occurred.
333
334   Only the formats ``qcow2``, ``qed`` and ``vdi`` support
335   consistency checks.
336
337   In case the image does not have any inconsistencies, check exits with ``0``.
338   Other exit codes indicate the kind of inconsistency found or if another error
339   occurred. The following table summarizes all exit codes of the check subcommand:
340
341   0
342     Check completed, the image is (now) consistent
343   1
344     Check not completed because of internal errors
345   2
346     Check completed, image is corrupted
347   3
348     Check completed, image has leaked clusters, but is not corrupted
349   63
350     Checks are not supported by the image format
351
352   If ``-r`` is specified, exit codes representing the image state refer to the
353   state after (the attempt at) repairing it. That is, a successful ``-r all``
354   will yield the exit code 0, independently of the image state before.
355
356 .. option:: commit [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [-t CACHE] [-b BASE] [-r RATE_LIMIT] [-d] [-p] FILENAME
357
358   Commit the changes recorded in *FILENAME* in its base image or backing file.
359   If the backing file is smaller than the snapshot, then the backing file will be
360   resized to be the same size as the snapshot.  If the snapshot is smaller than
361   the backing file, the backing file will not be truncated.  If you want the
362   backing file to match the size of the smaller snapshot, you can safely truncate
363   it yourself once the commit operation successfully completes.
364
365   The image *FILENAME* is emptied after the operation has succeeded. If you do
366   not need *FILENAME* afterwards and intend to drop it, you may skip emptying
367   *FILENAME* by specifying the ``-d`` flag.
368
369   If the backing chain of the given image file *FILENAME* has more than one
370   layer, the backing file into which the changes will be committed may be
371   specified as *BASE* (which has to be part of *FILENAME*'s backing
372   chain). If *BASE* is not specified, the immediate backing file of the top
373   image (which is *FILENAME*) will be used. Note that after a commit operation
374   all images between *BASE* and the top image will be invalid and may return
375   garbage data when read. For this reason, ``-b`` implies ``-d`` (so that
376   the top image stays valid).
377
378   The rate limit for the commit process is specified by ``-r``.
379
380 .. option:: compare [--object OBJECTDEF] [--image-opts] [-f FMT] [-F FMT] [-T SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1 FILENAME2
381
382   Check if two images have the same content. You can compare images with
383   different format or settings.
384
385   The format is probed unless you specify it by ``-f`` (used for
386   *FILENAME1*) and/or ``-F`` (used for *FILENAME2*) option.
387
388   By default, images with different size are considered identical if the larger
389   image contains only unallocated and/or zeroed sectors in the area after the end
390   of the other image. In addition, if any sector is not allocated in one image
391   and contains only zero bytes in the second one, it is evaluated as equal. You
392   can use Strict mode by specifying the ``-s`` option. When compare runs in
393   Strict mode, it fails in case image size differs or a sector is allocated in
394   one image and is not allocated in the second one.
395
396   By default, compare prints out a result message. This message displays
397   information that both images are same or the position of the first different
398   byte. In addition, result message can report different image size in case
399   Strict mode is used.
400
401   Compare exits with ``0`` in case the images are equal and with ``1``
402   in case the images differ. Other exit codes mean an error occurred during
403   execution and standard error output should contain an error message.
404   The following table sumarizes all exit codes of the compare subcommand:
405
406   0
407     Images are identical (or requested help was printed)
408   1
409     Images differ
410   2
411     Error on opening an image
412   3
413     Error on checking a sector allocation
414   4
415     Error on reading data
416
417 .. option:: convert [--object OBJECTDEF] [--image-opts] [--target-image-opts] [--target-is-zero] [--bitmaps] [-U] [-C] [-c] [-p] [-q] [-n] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-O OUTPUT_FMT] [-B BACKING_FILE] [-o OPTIONS] [-l SNAPSHOT_PARAM] [-S SPARSE_SIZE] [-r RATE_LIMIT] [-m NUM_COROUTINES] [-W] FILENAME [FILENAME2 [...]] OUTPUT_FILENAME
418
419   Convert the disk image *FILENAME* or a snapshot *SNAPSHOT_PARAM*
420   to disk image *OUTPUT_FILENAME* using format *OUTPUT_FMT*. It can
421   be optionally compressed (``-c`` option) or use any format specific
422   options like encryption (``-o`` option).
423
424   Only the formats ``qcow`` and ``qcow2`` support compression. The
425   compression is read-only. It means that if a compressed sector is
426   rewritten, then it is rewritten as uncompressed data.
427
428   Image conversion is also useful to get smaller image when using a
429   growable format such as ``qcow``: the empty sectors are detected and
430   suppressed from the destination image.
431
432   *SPARSE_SIZE* indicates the consecutive number of bytes (defaults to 4k)
433   that must contain only zeros for qemu-img to create a sparse image during
434   conversion. If *SPARSE_SIZE* is 0, the source will not be scanned for
435   unallocated or zero sectors, and the destination image will always be
436   fully allocated.
437
438   You can use the *BACKING_FILE* option to force the output image to be
439   created as a copy on write image of the specified base image; the
440   *BACKING_FILE* should have the same content as the input's base image,
441   however the path, image format, etc may differ.
442
443   If a relative path name is given, the backing file is looked up relative to
444   the directory containing *OUTPUT_FILENAME*.
445
446   If the ``-n`` option is specified, the target volume creation will be
447   skipped. This is useful for formats such as ``rbd`` if the target
448   volume has already been created with site specific options that cannot
449   be supplied through qemu-img.
450
451   Out of order writes can be enabled with ``-W`` to improve performance.
452   This is only recommended for preallocated devices like host devices or other
453   raw block devices. Out of order write does not work in combination with
454   creating compressed images.
455
456   *NUM_COROUTINES* specifies how many coroutines work in parallel during
457   the convert process (defaults to 8).
458
459 .. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE] [-F BACKING_FMT] [-u] [-o OPTIONS] FILENAME [SIZE]
460
461   Create the new disk image *FILENAME* of size *SIZE* and format
462   *FMT*. Depending on the file format, you can add one or more *OPTIONS*
463   that enable additional features of this format.
464
465   If the option *BACKING_FILE* is specified, then the image will record
466   only the differences from *BACKING_FILE*. No size needs to be specified in
467   this case. *BACKING_FILE* will never be modified unless you use the
468   ``commit`` monitor command (or qemu-img commit).
469
470   If a relative path name is given, the backing file is looked up relative to
471   the directory containing *FILENAME*.
472
473   Note that a given backing file will be opened to check that it is valid. Use
474   the ``-u`` option to enable unsafe backing file mode, which means that the
475   image will be created even if the associated backing file cannot be opened. A
476   matching backing file must be created or additional options be used to make the
477   backing file specification valid when you want to use an image created this
478   way.
479
480   The size can also be specified using the *SIZE* option with ``-o``,
481   it doesn't need to be specified separately in this case.
482
483
484 .. option:: dd [--image-opts] [-U] [-f FMT] [-O OUTPUT_FMT] [bs=BLOCK_SIZE] [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT
485
486   dd copies from *INPUT* file to *OUTPUT* file converting it from
487   *FMT* format to *OUTPUT_FMT* format.
488
489   The data is by default read and written using blocks of 512 bytes but can be
490   modified by specifying *BLOCK_SIZE*. If count=\ *BLOCKS* is specified
491   dd will stop reading input after reading *BLOCKS* input blocks.
492
493   The size syntax is similar to :manpage:`dd(1)`'s size syntax.
494
495 .. option:: info [--object OBJECTDEF] [--image-opts] [-f FMT] [--output=OFMT] [--backing-chain] [-U] FILENAME
496
497   Give information about the disk image *FILENAME*. Use it in
498   particular to know the size reserved on disk which can be different
499   from the displayed size. If VM snapshots are stored in the disk image,
500   they are displayed too.
501
502   If a disk image has a backing file chain, information about each disk image in
503   the chain can be recursively enumerated by using the option ``--backing-chain``.
504
505   For instance, if you have an image chain like:
506
507   ::
508
509     base.qcow2 <- snap1.qcow2 <- snap2.qcow2
510
511   To enumerate information about each disk image in the above chain, starting from top to base, do:
512
513   ::
514
515     qemu-img info --backing-chain snap2.qcow2
516
517   The command can output in the format *OFMT* which is either ``human`` or
518   ``json``.  The JSON output is an object of QAPI type ``ImageInfo``; with
519   ``--backing-chain``, it is an array of ``ImageInfo`` objects.
520
521   ``--output=human`` reports the following information (for every image in the
522   chain):
523
524   *image*
525     The image file name
526
527   *file format*
528     The image format
529
530   *virtual size*
531     The size of the guest disk
532
533   *disk size*
534     How much space the image file occupies on the host file system (may be
535     shown as 0 if this information is unavailable, e.g. because there is no
536     file system)
537
538   *cluster_size*
539     Cluster size of the image format, if applicable
540
541   *encrypted*
542     Whether the image is encrypted (only present if so)
543
544   *cleanly shut down*
545     This is shown as ``no`` if the image is dirty and will have to be
546     auto-repaired the next time it is opened in qemu.
547
548   *backing file*
549     The backing file name, if present
550
551   *backing file format*
552     The format of the backing file, if the image enforces it
553
554   *Snapshot list*
555     A list of all internal snapshots
556
557   *Format specific information*
558     Further information whose structure depends on the image format.  This
559     section is a textual representation of the respective
560     ``ImageInfoSpecific*`` QAPI object (e.g. ``ImageInfoSpecificQCow2``
561     for qcow2 images).
562
563 .. option:: map [--object OBJECTDEF] [--image-opts] [-f FMT] [--start-offset=OFFSET] [--max-length=LEN] [--output=OFMT] [-U] FILENAME
564
565   Dump the metadata of image *FILENAME* and its backing file chain.
566   In particular, this commands dumps the allocation state of every sector
567   of *FILENAME*, together with the topmost file that allocates it in
568   the backing file chain.
569
570   Two option formats are possible.  The default format (``human``)
571   only dumps known-nonzero areas of the file.  Known-zero parts of the
572   file are omitted altogether, and likewise for parts that are not allocated
573   throughout the chain.  ``qemu-img`` output will identify a file
574   from where the data can be read, and the offset in the file.  Each line
575   will include four fields, the first three of which are hexadecimal
576   numbers.  For example the first line of:
577
578   ::
579
580     Offset          Length          Mapped to       File
581     0               0x20000         0x50000         /tmp/overlay.qcow2
582     0x100000        0x10000         0x95380000      /tmp/backing.qcow2
583
584   means that 0x20000 (131072) bytes starting at offset 0 in the image are
585   available in /tmp/overlay.qcow2 (opened in ``raw`` format) starting
586   at offset 0x50000 (327680).  Data that is compressed, encrypted, or
587   otherwise not available in raw format will cause an error if ``human``
588   format is in use.  Note that file names can include newlines, thus it is
589   not safe to parse this output format in scripts.
590
591   The alternative format ``json`` will return an array of dictionaries
592   in JSON format.  It will include similar information in
593   the ``start``, ``length``, ``offset`` fields;
594   it will also include other more specific information:
595
596   - whether the sectors contain actual data or not (boolean field ``data``;
597     if false, the sectors are either unallocated or stored as optimized
598     all-zero clusters);
599   - whether the data is known to read as zero (boolean field ``zero``);
600   - in order to make the output shorter, the target file is expressed as
601     a ``depth``; for example, a depth of 2 refers to the backing file
602     of the backing file of *FILENAME*.
603
604   In JSON format, the ``offset`` field is optional; it is absent in
605   cases where ``human`` format would omit the entry or exit with an error.
606   If ``data`` is false and the ``offset`` field is present, the
607   corresponding sectors in the file are not yet in use, but they are
608   preallocated.
609
610   For more information, consult ``include/block/block.h`` in QEMU's
611   source code.
612
613 .. option:: measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--object OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]
614
615   Calculate the file size required for a new image.  This information
616   can be used to size logical volumes or SAN LUNs appropriately for
617   the image that will be placed in them.  The values reported are
618   guaranteed to be large enough to fit the image.  The command can
619   output in the format *OFMT* which is either ``human`` or ``json``.
620   The JSON output is an object of QAPI type ``BlockMeasureInfo``.
621
622   If the size *N* is given then act as if creating a new empty image file
623   using ``qemu-img create``.  If *FILENAME* is given then act as if
624   converting an existing image file using ``qemu-img convert``.  The format
625   of the new file is given by *OUTPUT_FMT* while the format of an existing
626   file is given by *FMT*.
627
628   A snapshot in an existing image can be specified using *SNAPSHOT_PARAM*.
629
630   The following fields are reported:
631
632   ::
633
634     required size: 524288
635     fully allocated size: 1074069504
636     bitmaps size: 0
637
638   The ``required size`` is the file size of the new image.  It may be smaller
639   than the virtual disk size if the image format supports compact representation.
640
641   The ``fully allocated size`` is the file size of the new image once data has
642   been written to all sectors.  This is the maximum size that the image file can
643   occupy with the exception of internal snapshots, dirty bitmaps, vmstate data,
644   and other advanced image format features.
645
646   The ``bitmaps size`` is the additional size required in order to
647   copy bitmaps from a source image in addition to the guest-visible
648   data; the line is omitted if either source or destination lacks
649   bitmap support, or 0 if bitmaps are supported but there is nothing
650   to copy.
651
652 .. option:: snapshot [--object OBJECTDEF] [--image-opts] [-U] [-q] [-l | -a SNAPSHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME
653
654   List, apply, create or delete snapshots in image *FILENAME*.
655
656 .. option:: rebase [--object OBJECTDEF] [--image-opts] [-U] [-q] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-p] [-u] -b BACKING_FILE [-F BACKING_FMT] FILENAME
657
658   Changes the backing file of an image. Only the formats ``qcow2`` and
659   ``qed`` support changing the backing file.
660
661   The backing file is changed to *BACKING_FILE* and (if the image format of
662   *FILENAME* supports this) the backing file format is changed to
663   *BACKING_FMT*. If *BACKING_FILE* is specified as "" (the empty
664   string), then the image is rebased onto no backing file (i.e. it will exist
665   independently of any backing file).
666
667   If a relative path name is given, the backing file is looked up relative to
668   the directory containing *FILENAME*.
669
670   *CACHE* specifies the cache mode to be used for *FILENAME*, whereas
671   *SRC_CACHE* specifies the cache mode for reading backing files.
672
673   There are two different modes in which ``rebase`` can operate:
674
675   Safe mode
676     This is the default mode and performs a real rebase operation. The
677     new backing file may differ from the old one and qemu-img rebase
678     will take care of keeping the guest-visible content of *FILENAME*
679     unchanged.
680
681     In order to achieve this, any clusters that differ between
682     *BACKING_FILE* and the old backing file of *FILENAME* are merged
683     into *FILENAME* before actually changing the backing file.
684
685     Note that the safe mode is an expensive operation, comparable to
686     converting an image. It only works if the old backing file still
687     exists.
688
689   Unsafe mode
690     qemu-img uses the unsafe mode if ``-u`` is specified. In this
691     mode, only the backing file name and format of *FILENAME* is changed
692     without any checks on the file contents. The user must take care of
693     specifying the correct new backing file, or the guest-visible
694     content of the image will be corrupted.
695
696     This mode is useful for renaming or moving the backing file to
697     somewhere else.  It can be used without an accessible old backing
698     file, i.e. you can use it to fix an image whose backing file has
699     already been moved/renamed.
700
701   You can use ``rebase`` to perform a "diff" operation on two
702   disk images.  This can be useful when you have copied or cloned
703   a guest, and you want to get back to a thin image on top of a
704   template or base image.
705
706   Say that ``base.img`` has been cloned as ``modified.img`` by
707   copying it, and that the ``modified.img`` guest has run so there
708   are now some changes compared to ``base.img``.  To construct a thin
709   image called ``diff.qcow2`` that contains just the differences, do:
710
711   ::
712
713     qemu-img create -f qcow2 -b modified.img diff.qcow2
714     qemu-img rebase -b base.img diff.qcow2
715
716   At this point, ``modified.img`` can be discarded, since
717   ``base.img + diff.qcow2`` contains the same information.
718
719 .. option:: resize [--object OBJECTDEF] [--image-opts] [-f FMT] [--preallocation=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE
720
721   Change the disk image as if it had been created with *SIZE*.
722
723   Before using this command to shrink a disk image, you MUST use file system and
724   partitioning tools inside the VM to reduce allocated file systems and partition
725   sizes accordingly.  Failure to do so will result in data loss!
726
727   When shrinking images, the ``--shrink`` option must be given. This informs
728   qemu-img that the user acknowledges all loss of data beyond the truncated
729   image's end.
730
731   After using this command to grow a disk image, you must use file system and
732   partitioning tools inside the VM to actually begin using the new space on the
733   device.
734
735   When growing an image, the ``--preallocation`` option may be used to specify
736   how the additional image area should be allocated on the host.  See the format
737   description in the :ref:`notes` section which values are allowed.  Using this
738   option may result in slightly more data being allocated than necessary.
739
740 .. _notes:
741
742 Notes
743 -----
744
745 Supported image file formats:
746
747 ``raw``
748
749   Raw disk image format (default). This format has the advantage of
750   being simple and easily exportable to all other emulators. If your
751   file system supports *holes* (for example in ext2 or ext3 on
752   Linux or NTFS on Windows), then only the written sectors will reserve
753   space. Use ``qemu-img info`` to know the real size used by the
754   image or ``ls -ls`` on Unix/Linux.
755
756   Supported options:
757
758   ``preallocation``
759     Preallocation mode (allowed values: ``off``, ``falloc``,
760     ``full``).  ``falloc`` mode preallocates space for image by
761     calling ``posix_fallocate()``.  ``full`` mode preallocates space
762     for image by writing data to underlying storage.  This data may or
763     may not be zero, depending on the storage location.
764
765 ``qcow2``
766
767   QEMU image format, the most versatile format. Use it to have smaller
768   images (useful if your filesystem does not supports holes, for example
769   on Windows), optional AES encryption, zlib based compression and
770   support of multiple VM snapshots.
771
772   Supported options:
773
774   ``compat``
775     Determines the qcow2 version to use. ``compat=0.10`` uses the
776     traditional image format that can be read by any QEMU since 0.10.
777     ``compat=1.1`` enables image format extensions that only QEMU 1.1 and
778     newer understand (this is the default). Amongst others, this includes zero
779     clusters, which allow efficient copy-on-read for sparse images.
780
781   ``backing_file``
782     File name of a base image (see ``create`` subcommand)
783
784   ``backing_fmt``
785     Image format of the base image
786
787   ``encryption``
788     If this option is set to ``on``, the image is encrypted with
789     128-bit AES-CBC.
790
791     The use of encryption in qcow and qcow2 images is considered to be
792     flawed by modern cryptography standards, suffering from a number
793     of design problems:
794
795     - The AES-CBC cipher is used with predictable initialization
796       vectors based on the sector number. This makes it vulnerable to
797       chosen plaintext attacks which can reveal the existence of
798       encrypted data.
799
800     - The user passphrase is directly used as the encryption key. A
801       poorly chosen or short passphrase will compromise the security
802       of the encryption.
803
804     - In the event of the passphrase being compromised there is no way
805       to change the passphrase to protect data in any qcow images. The
806       files must be cloned, using a different encryption passphrase in
807       the new file. The original file must then be securely erased
808       using a program like shred, though even this is ineffective with
809       many modern storage technologies.
810
811     - Initialization vectors used to encrypt sectors are based on the
812       guest virtual sector number, instead of the host physical
813       sector. When a disk image has multiple internal snapshots this
814       means that data in multiple physical sectors is encrypted with
815       the same initialization vector. With the CBC mode, this opens
816       the possibility of watermarking attacks if the attack can
817       collect multiple sectors encrypted with the same IV and some
818       predictable data. Having multiple qcow2 images with the same
819       passphrase also exposes this weakness since the passphrase is
820       directly used as the key.
821
822     Use of qcow / qcow2 encryption is thus strongly discouraged. Users are
823     recommended to use an alternative encryption technology such as the
824     Linux dm-crypt / LUKS system.
825
826   ``cluster_size``
827     Changes the qcow2 cluster size (must be between 512 and
828     2M). Smaller cluster sizes can improve the image file size whereas
829     larger cluster sizes generally provide better performance.
830
831   ``preallocation``
832     Preallocation mode (allowed values: ``off``, ``metadata``,
833     ``falloc``, ``full``). An image with preallocated metadata is
834     initially larger but can improve performance when the image needs
835     to grow. ``falloc`` and ``full`` preallocations are like the same
836     options of ``raw`` format, but sets up metadata also.
837
838   ``lazy_refcounts``
839     If this option is set to ``on``, reference count updates are
840     postponed with the goal of avoiding metadata I/O and improving
841     performance. This is particularly interesting with
842     ``cache=writethrough`` which doesn't batch metadata
843     updates. The tradeoff is that after a host crash, the reference
844     count tables must be rebuilt, i.e. on the next open an (automatic)
845     ``qemu-img check -r all`` is required, which may take some time.
846
847     This option can only be enabled if ``compat=1.1`` is specified.
848
849   ``nocow``
850     If this option is set to ``on``, it will turn off COW of the file. It's
851     only valid on btrfs, no effect on other file systems.
852
853     Btrfs has low performance when hosting a VM image file, even more
854     when the guest on the VM also using btrfs as file system. Turning
855     off COW is a way to mitigate this bad performance. Generally there
856     are two ways to turn off COW on btrfs:
857
858     - Disable it by mounting with nodatacow, then all newly created files
859       will be NOCOW
860     - For an empty file, add the NOCOW file attribute. That's what this
861       option does.
862
863     Note: this option is only valid to new or empty files. If there is
864     an existing file which is COW and has data blocks already, it
865     couldn't be changed to NOCOW by setting ``nocow=on``. One can
866     issue ``lsattr filename`` to check if the NOCOW flag is set or not
867     (Capital 'C' is NOCOW flag).
868
869   ``data_file``
870     Filename where all guest data will be stored. If this option is used,
871     the qcow2 file will only contain the image's metadata.
872
873     Note: Data loss will occur if the given filename already exists when
874     using this option with ``qemu-img create`` since ``qemu-img`` will create
875     the data file anew, overwriting the file's original contents. To simply
876     update the reference to point to the given pre-existing file, use
877     ``qemu-img amend``.
878
879   ``data_file_raw``
880     If this option is set to ``on``, QEMU will always keep the external data
881     file consistent as a standalone read-only raw image.
882
883     It does this by forwarding all write accesses to the qcow2 file through to
884     the raw data file, including their offsets. Therefore, data that is visible
885     on the qcow2 node (i.e., to the guest) at some offset is visible at the same
886     offset in the raw data file. This results in a read-only raw image. Writes
887     that bypass the qcow2 metadata may corrupt the qcow2 metadata because the
888     out-of-band writes may result in the metadata falling out of sync with the
889     raw image.
890
891     If this option is ``off``, QEMU will use the data file to store data in an
892     arbitrary manner. The file’s content will not make sense without the
893     accompanying qcow2 metadata. Where data is written will have no relation to
894     its offset as seen by the guest, and some writes (specifically zero writes)
895     may not be forwarded to the data file at all, but will only be handled by
896     modifying qcow2 metadata.
897
898     This option can only be enabled if ``data_file`` is set.
899
900 ``Other``
901
902   QEMU also supports various other image file formats for
903   compatibility with older QEMU versions or other hypervisors,
904   including VMDK, VDI, VHD (vpc), VHDX, qcow1 and QED. For a full list
905   of supported formats see ``qemu-img --help``.  For a more detailed
906   description of these formats, see the QEMU block drivers reference
907   documentation.
908
909   The main purpose of the block drivers for these formats is image
910   conversion.  For running VMs, it is recommended to convert the disk
911   images to either raw or qcow2 in order to achieve good performance.