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