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