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