meson: convert hw/vfio
[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] [-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 .. option:: compare [--object OBJECTDEF] [--image-opts] [-f FMT] [-F FMT] [-T SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1 FILENAME2
375
376   Check if two images have the same content. You can compare images with
377   different format or settings.
378
379   The format is probed unless you specify it by ``-f`` (used for
380   *FILENAME1*) and/or ``-F`` (used for *FILENAME2*) option.
381
382   By default, images with different size are considered identical if the larger
383   image contains only unallocated and/or zeroed sectors in the area after the end
384   of the other image. In addition, if any sector is not allocated in one image
385   and contains only zero bytes in the second one, it is evaluated as equal. You
386   can use Strict mode by specifying the ``-s`` option. When compare runs in
387   Strict mode, it fails in case image size differs or a sector is allocated in
388   one image and is not allocated in the second one.
389
390   By default, compare prints out a result message. This message displays
391   information that both images are same or the position of the first different
392   byte. In addition, result message can report different image size in case
393   Strict mode is used.
394
395   Compare exits with ``0`` in case the images are equal and with ``1``
396   in case the images differ. Other exit codes mean an error occurred during
397   execution and standard error output should contain an error message.
398   The following table sumarizes all exit codes of the compare subcommand:
399
400   0
401     Images are identical
402   1
403     Images differ
404   2
405     Error on opening an image
406   3
407     Error on checking a sector allocation
408   4
409     Error on reading data
410
411 .. 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
412
413   Convert the disk image *FILENAME* or a snapshot *SNAPSHOT_PARAM*
414   to disk image *OUTPUT_FILENAME* using format *OUTPUT_FMT*. It can
415   be optionally compressed (``-c`` option) or use any format specific
416   options like encryption (``-o`` option).
417
418   Only the formats ``qcow`` and ``qcow2`` support compression. The
419   compression is read-only. It means that if a compressed sector is
420   rewritten, then it is rewritten as uncompressed data.
421
422   Image conversion is also useful to get smaller image when using a
423   growable format such as ``qcow``: the empty sectors are detected and
424   suppressed from the destination image.
425
426   *SPARSE_SIZE* indicates the consecutive number of bytes (defaults to 4k)
427   that must contain only zeros for qemu-img to create a sparse image during
428   conversion. If *SPARSE_SIZE* is 0, the source will not be scanned for
429   unallocated or zero sectors, and the destination image will always be
430   fully allocated.
431
432   You can use the *BACKING_FILE* option to force the output image to be
433   created as a copy on write image of the specified base image; the
434   *BACKING_FILE* should have the same content as the input's base image,
435   however the path, image format, etc may differ.
436
437   If a relative path name is given, the backing file is looked up relative to
438   the directory containing *OUTPUT_FILENAME*.
439
440   If the ``-n`` option is specified, the target volume creation will be
441   skipped. This is useful for formats such as ``rbd`` if the target
442   volume has already been created with site specific options that cannot
443   be supplied through qemu-img.
444
445   Out of order writes can be enabled with ``-W`` to improve performance.
446   This is only recommended for preallocated devices like host devices or other
447   raw block devices. Out of order write does not work in combination with
448   creating compressed images.
449
450   *NUM_COROUTINES* specifies how many coroutines work in parallel during
451   the convert process (defaults to 8).
452
453 .. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE] [-F BACKING_FMT] [-u] [-o OPTIONS] FILENAME [SIZE]
454
455   Create the new disk image *FILENAME* of size *SIZE* and format
456   *FMT*. Depending on the file format, you can add one or more *OPTIONS*
457   that enable additional features of this format.
458
459   If the option *BACKING_FILE* is specified, then the image will record
460   only the differences from *BACKING_FILE*. No size needs to be specified in
461   this case. *BACKING_FILE* will never be modified unless you use the
462   ``commit`` monitor command (or qemu-img commit).
463
464   If a relative path name is given, the backing file is looked up relative to
465   the directory containing *FILENAME*.
466
467   Note that a given backing file will be opened to check that it is valid. Use
468   the ``-u`` option to enable unsafe backing file mode, which means that the
469   image will be created even if the associated backing file cannot be opened. A
470   matching backing file must be created or additional options be used to make the
471   backing file specification valid when you want to use an image created this
472   way.
473
474   The size can also be specified using the *SIZE* option with ``-o``,
475   it doesn't need to be specified separately in this case.
476
477
478 .. option:: dd [--image-opts] [-U] [-f FMT] [-O OUTPUT_FMT] [bs=BLOCK_SIZE] [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT
479
480   dd copies from *INPUT* file to *OUTPUT* file converting it from
481   *FMT* format to *OUTPUT_FMT* format.
482
483   The data is by default read and written using blocks of 512 bytes but can be
484   modified by specifying *BLOCK_SIZE*. If count=\ *BLOCKS* is specified
485   dd will stop reading input after reading *BLOCKS* input blocks.
486
487   The size syntax is similar to :manpage:`dd(1)`'s size syntax.
488
489 .. option:: info [--object OBJECTDEF] [--image-opts] [-f FMT] [--output=OFMT] [--backing-chain] [-U] FILENAME
490
491   Give information about the disk image *FILENAME*. Use it in
492   particular to know the size reserved on disk which can be different
493   from the displayed size. If VM snapshots are stored in the disk image,
494   they are displayed too.
495
496   If a disk image has a backing file chain, information about each disk image in
497   the chain can be recursively enumerated by using the option ``--backing-chain``.
498
499   For instance, if you have an image chain like:
500
501   ::
502
503     base.qcow2 <- snap1.qcow2 <- snap2.qcow2
504
505   To enumerate information about each disk image in the above chain, starting from top to base, do:
506
507   ::
508
509     qemu-img info --backing-chain snap2.qcow2
510
511   The command can output in the format *OFMT* which is either ``human`` or
512   ``json``.  The JSON output is an object of QAPI type ``ImageInfo``; with
513   ``--backing-chain``, it is an array of ``ImageInfo`` objects.
514
515   ``--output=human`` reports the following information (for every image in the
516   chain):
517
518   *image*
519     The image file name
520
521   *file format*
522     The image format
523
524   *virtual size*
525     The size of the guest disk
526
527   *disk size*
528     How much space the image file occupies on the host file system (may be
529     shown as 0 if this information is unavailable, e.g. because there is no
530     file system)
531
532   *cluster_size*
533     Cluster size of the image format, if applicable
534
535   *encrypted*
536     Whether the image is encrypted (only present if so)
537
538   *cleanly shut down*
539     This is shown as ``no`` if the image is dirty and will have to be
540     auto-repaired the next time it is opened in qemu.
541
542   *backing file*
543     The backing file name, if present
544
545   *backing file format*
546     The format of the backing file, if the image enforces it
547
548   *Snapshot list*
549     A list of all internal snapshots
550
551   *Format specific information*
552     Further information whose structure depends on the image format.  This
553     section is a textual representation of the respective
554     ``ImageInfoSpecific*`` QAPI object (e.g. ``ImageInfoSpecificQCow2``
555     for qcow2 images).
556
557 .. option:: map [--object OBJECTDEF] [--image-opts] [-f FMT] [--start-offset=OFFSET] [--max-length=LEN] [--output=OFMT] [-U] FILENAME
558
559   Dump the metadata of image *FILENAME* and its backing file chain.
560   In particular, this commands dumps the allocation state of every sector
561   of *FILENAME*, together with the topmost file that allocates it in
562   the backing file chain.
563
564   Two option formats are possible.  The default format (``human``)
565   only dumps known-nonzero areas of the file.  Known-zero parts of the
566   file are omitted altogether, and likewise for parts that are not allocated
567   throughout the chain.  ``qemu-img`` output will identify a file
568   from where the data can be read, and the offset in the file.  Each line
569   will include four fields, the first three of which are hexadecimal
570   numbers.  For example the first line of:
571
572   ::
573
574     Offset          Length          Mapped to       File
575     0               0x20000         0x50000         /tmp/overlay.qcow2
576     0x100000        0x10000         0x95380000      /tmp/backing.qcow2
577
578   means that 0x20000 (131072) bytes starting at offset 0 in the image are
579   available in /tmp/overlay.qcow2 (opened in ``raw`` format) starting
580   at offset 0x50000 (327680).  Data that is compressed, encrypted, or
581   otherwise not available in raw format will cause an error if ``human``
582   format is in use.  Note that file names can include newlines, thus it is
583   not safe to parse this output format in scripts.
584
585   The alternative format ``json`` will return an array of dictionaries
586   in JSON format.  It will include similar information in
587   the ``start``, ``length``, ``offset`` fields;
588   it will also include other more specific information:
589
590   - whether the sectors contain actual data or not (boolean field ``data``;
591     if false, the sectors are either unallocated or stored as optimized
592     all-zero clusters);
593   - whether the data is known to read as zero (boolean field ``zero``);
594   - in order to make the output shorter, the target file is expressed as
595     a ``depth``; for example, a depth of 2 refers to the backing file
596     of the backing file of *FILENAME*.
597
598   In JSON format, the ``offset`` field is optional; it is absent in
599   cases where ``human`` format would omit the entry or exit with an error.
600   If ``data`` is false and the ``offset`` field is present, the
601   corresponding sectors in the file are not yet in use, but they are
602   preallocated.
603
604   For more information, consult ``include/block/block.h`` in QEMU's
605   source code.
606
607 .. option:: measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--object OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]
608
609   Calculate the file size required for a new image.  This information
610   can be used to size logical volumes or SAN LUNs appropriately for
611   the image that will be placed in them.  The values reported are
612   guaranteed to be large enough to fit the image.  The command can
613   output in the format *OFMT* which is either ``human`` or ``json``.
614   The JSON output is an object of QAPI type ``BlockMeasureInfo``.
615
616   If the size *N* is given then act as if creating a new empty image file
617   using ``qemu-img create``.  If *FILENAME* is given then act as if
618   converting an existing image file using ``qemu-img convert``.  The format
619   of the new file is given by *OUTPUT_FMT* while the format of an existing
620   file is given by *FMT*.
621
622   A snapshot in an existing image can be specified using *SNAPSHOT_PARAM*.
623
624   The following fields are reported:
625
626   ::
627
628     required size: 524288
629     fully allocated size: 1074069504
630     bitmaps size: 0
631
632   The ``required size`` is the file size of the new image.  It may be smaller
633   than the virtual disk size if the image format supports compact representation.
634
635   The ``fully allocated size`` is the file size of the new image once data has
636   been written to all sectors.  This is the maximum size that the image file can
637   occupy with the exception of internal snapshots, dirty bitmaps, vmstate data,
638   and other advanced image format features.
639
640   The ``bitmaps size`` is the additional size required in order to
641   copy bitmaps from a source image in addition to the guest-visible
642   data; the line is omitted if either source or destination lacks
643   bitmap support, or 0 if bitmaps are supported but there is nothing
644   to copy.
645
646 .. option:: snapshot [--object OBJECTDEF] [--image-opts] [-U] [-q] [-l | -a SNAPSHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME
647
648   List, apply, create or delete snapshots in image *FILENAME*.
649
650 .. option:: rebase [--object OBJECTDEF] [--image-opts] [-U] [-q] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-p] [-u] -b BACKING_FILE [-F BACKING_FMT] FILENAME
651
652   Changes the backing file of an image. Only the formats ``qcow2`` and
653   ``qed`` support changing the backing file.
654
655   The backing file is changed to *BACKING_FILE* and (if the image format of
656   *FILENAME* supports this) the backing file format is changed to
657   *BACKING_FMT*. If *BACKING_FILE* is specified as "" (the empty
658   string), then the image is rebased onto no backing file (i.e. it will exist
659   independently of any backing file).
660
661   If a relative path name is given, the backing file is looked up relative to
662   the directory containing *FILENAME*.
663
664   *CACHE* specifies the cache mode to be used for *FILENAME*, whereas
665   *SRC_CACHE* specifies the cache mode for reading backing files.
666
667   There are two different modes in which ``rebase`` can operate:
668
669   Safe mode
670     This is the default mode and performs a real rebase operation. The
671     new backing file may differ from the old one and qemu-img rebase
672     will take care of keeping the guest-visible content of *FILENAME*
673     unchanged.
674
675     In order to achieve this, any clusters that differ between
676     *BACKING_FILE* and the old backing file of *FILENAME* are merged
677     into *FILENAME* before actually changing the backing file.
678
679     Note that the safe mode is an expensive operation, comparable to
680     converting an image. It only works if the old backing file still
681     exists.
682
683   Unsafe mode
684     qemu-img uses the unsafe mode if ``-u`` is specified. In this
685     mode, only the backing file name and format of *FILENAME* is changed
686     without any checks on the file contents. The user must take care of
687     specifying the correct new backing file, or the guest-visible
688     content of the image will be corrupted.
689
690     This mode is useful for renaming or moving the backing file to
691     somewhere else.  It can be used without an accessible old backing
692     file, i.e. you can use it to fix an image whose backing file has
693     already been moved/renamed.
694
695   You can use ``rebase`` to perform a "diff" operation on two
696   disk images.  This can be useful when you have copied or cloned
697   a guest, and you want to get back to a thin image on top of a
698   template or base image.
699
700   Say that ``base.img`` has been cloned as ``modified.img`` by
701   copying it, and that the ``modified.img`` guest has run so there
702   are now some changes compared to ``base.img``.  To construct a thin
703   image called ``diff.qcow2`` that contains just the differences, do:
704
705   ::
706
707     qemu-img create -f qcow2 -b modified.img diff.qcow2
708     qemu-img rebase -b base.img diff.qcow2
709
710   At this point, ``modified.img`` can be discarded, since
711   ``base.img + diff.qcow2`` contains the same information.
712
713 .. option:: resize [--object OBJECTDEF] [--image-opts] [-f FMT] [--preallocation=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE
714
715   Change the disk image as if it had been created with *SIZE*.
716
717   Before using this command to shrink a disk image, you MUST use file system and
718   partitioning tools inside the VM to reduce allocated file systems and partition
719   sizes accordingly.  Failure to do so will result in data loss!
720
721   When shrinking images, the ``--shrink`` option must be given. This informs
722   qemu-img that the user acknowledges all loss of data beyond the truncated
723   image's end.
724
725   After using this command to grow a disk image, you must use file system and
726   partitioning tools inside the VM to actually begin using the new space on the
727   device.
728
729   When growing an image, the ``--preallocation`` option may be used to specify
730   how the additional image area should be allocated on the host.  See the format
731   description in the :ref:`notes` section which values are allowed.  Using this
732   option may result in slightly more data being allocated than necessary.
733
734 .. _notes:
735
736 Notes
737 -----
738
739 Supported image file formats:
740
741 ``raw``
742
743   Raw disk image format (default). This format has the advantage of
744   being simple and easily exportable to all other emulators. If your
745   file system supports *holes* (for example in ext2 or ext3 on
746   Linux or NTFS on Windows), then only the written sectors will reserve
747   space. Use ``qemu-img info`` to know the real size used by the
748   image or ``ls -ls`` on Unix/Linux.
749
750   Supported options:
751
752   ``preallocation``
753     Preallocation mode (allowed values: ``off``, ``falloc``,
754     ``full``).  ``falloc`` mode preallocates space for image by
755     calling ``posix_fallocate()``.  ``full`` mode preallocates space
756     for image by writing data to underlying storage.  This data may or
757     may not be zero, depending on the storage location.
758
759 ``qcow2``
760
761   QEMU image format, the most versatile format. Use it to have smaller
762   images (useful if your filesystem does not supports holes, for example
763   on Windows), optional AES encryption, zlib based compression and
764   support of multiple VM snapshots.
765
766   Supported options:
767
768   ``compat``
769     Determines the qcow2 version to use. ``compat=0.10`` uses the
770     traditional image format that can be read by any QEMU since 0.10.
771     ``compat=1.1`` enables image format extensions that only QEMU 1.1 and
772     newer understand (this is the default). Amongst others, this includes zero
773     clusters, which allow efficient copy-on-read for sparse images.
774
775   ``backing_file``
776     File name of a base image (see ``create`` subcommand)
777
778   ``backing_fmt``
779     Image format of the base image
780
781   ``encryption``
782     If this option is set to ``on``, the image is encrypted with
783     128-bit AES-CBC.
784
785     The use of encryption in qcow and qcow2 images is considered to be
786     flawed by modern cryptography standards, suffering from a number
787     of design problems:
788
789     - The AES-CBC cipher is used with predictable initialization
790       vectors based on the sector number. This makes it vulnerable to
791       chosen plaintext attacks which can reveal the existence of
792       encrypted data.
793
794     - The user passphrase is directly used as the encryption key. A
795       poorly chosen or short passphrase will compromise the security
796       of the encryption.
797
798     - In the event of the passphrase being compromised there is no way
799       to change the passphrase to protect data in any qcow images. The
800       files must be cloned, using a different encryption passphrase in
801       the new file. The original file must then be securely erased
802       using a program like shred, though even this is ineffective with
803       many modern storage technologies.
804
805     - Initialization vectors used to encrypt sectors are based on the
806       guest virtual sector number, instead of the host physical
807       sector. When a disk image has multiple internal snapshots this
808       means that data in multiple physical sectors is encrypted with
809       the same initialization vector. With the CBC mode, this opens
810       the possibility of watermarking attacks if the attack can
811       collect multiple sectors encrypted with the same IV and some
812       predictable data. Having multiple qcow2 images with the same
813       passphrase also exposes this weakness since the passphrase is
814       directly used as the key.
815
816     Use of qcow / qcow2 encryption is thus strongly discouraged. Users are
817     recommended to use an alternative encryption technology such as the
818     Linux dm-crypt / LUKS system.
819
820   ``cluster_size``
821     Changes the qcow2 cluster size (must be between 512 and
822     2M). Smaller cluster sizes can improve the image file size whereas
823     larger cluster sizes generally provide better performance.
824
825   ``preallocation``
826     Preallocation mode (allowed values: ``off``, ``metadata``,
827     ``falloc``, ``full``). An image with preallocated metadata is
828     initially larger but can improve performance when the image needs
829     to grow. ``falloc`` and ``full`` preallocations are like the same
830     options of ``raw`` format, but sets up metadata also.
831
832   ``lazy_refcounts``
833     If this option is set to ``on``, reference count updates are
834     postponed with the goal of avoiding metadata I/O and improving
835     performance. This is particularly interesting with
836     ``cache=writethrough`` which doesn't batch metadata
837     updates. The tradeoff is that after a host crash, the reference
838     count tables must be rebuilt, i.e. on the next open an (automatic)
839     ``qemu-img check -r all`` is required, which may take some time.
840
841     This option can only be enabled if ``compat=1.1`` is specified.
842
843   ``nocow``
844     If this option is set to ``on``, it will turn off COW of the file. It's
845     only valid on btrfs, no effect on other file systems.
846
847     Btrfs has low performance when hosting a VM image file, even more
848     when the guest on the VM also using btrfs as file system. Turning
849     off COW is a way to mitigate this bad performance. Generally there
850     are two ways to turn off COW on btrfs:
851
852     - Disable it by mounting with nodatacow, then all newly created files
853       will be NOCOW
854     - For an empty file, add the NOCOW file attribute. That's what this
855       option does.
856
857     Note: this option is only valid to new or empty files. If there is
858     an existing file which is COW and has data blocks already, it
859     couldn't be changed to NOCOW by setting ``nocow=on``. One can
860     issue ``lsattr filename`` to check if the NOCOW flag is set or not
861     (Capital 'C' is NOCOW flag).
862
863 ``Other``
864
865   QEMU also supports various other image file formats for
866   compatibility with older QEMU versions or other hypervisors,
867   including VMDK, VDI, VHD (vpc), VHDX, qcow1 and QED. For a full list
868   of supported formats see ``qemu-img --help``.  For a more detailed
869   description of these formats, see the QEMU block drivers reference
870   documentation.
871
872   The main purpose of the block drivers for these formats is image
873   conversion.  For running VMs, it is recommended to convert the disk
874   images to either raw or qcow2 in order to achieve good performance.