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