Lines Matching full:the
17 machine or any other process; this may destroy the image. Also, be aware that
40 The following commands are supported:
48 *FMT* is the disk image format. It is guessed automatically in most
49 cases. See below for a description of the supported disk formats.
51 *SIZE* is the disk image size in bytes. Optional suffixes ``k`` or
55 *OUTPUT_FILENAME* is the destination disk image filename.
57 *OUTPUT_FMT* is the destination format.
60 name=value format. Use ``-o help`` for an overview of the options supported
61 by the used format or see the format descriptions below for details.
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.
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
81 Indicates that the source *FILENAME* parameter is to be interpreted as a
83 exclusive with the *-f* parameter.
87 Indicates that the OUTPUT_FILENAME parameter(s) are to be interpreted as
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
95 If specified, ``qemu-img`` will open the image in shared mode, allowing
97 get the image information (with 'info' subcommand) when the image is used by a
112 For qcow2, the compression algorithm can be specified with the ``-o
117 With or without a command, shows help and lists the supported formats.
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
133 Indicates the consecutive number of bytes that must contain only zeros
135 rounded down to the nearest 512 bytes. You may use the common size suffixes
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
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
172 Additionally copy all persistent bitmaps from the top layer of the source
176 Skip the creation of the target volume
180 Number of parallel coroutines for the convert process
184 Allow out-of-order writes to the destination. This option improves performance,
191 improve performance if the data is remote, such as with NFS or iSCSI backends,
193 allocated target image depending on the host support for getting allocation
198 Rate limit for the convert process
203 will still be printed. Areas that cannot be read from the source will be
208 Assume that reading the destination image will always return
210 that has a backing file. It is required to also use the ``-n``
219 Defines the block size
223 Sets the number of input blocks to copy
227 Sets the input file
231 Sets the output file
235 Sets the number of input blocks to skip
243 Is the name of the snapshot to create, apply or delete
259 Lists all snapshots in the given image
267 Amends the image format specific *OPTIONS* for the image file
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
275 erase the last encryption key, and to overwrite an active encryption key.
279 Run a simple sequential I/O benchmark on the specified image. If ``-w`` is
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,
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
291 ``--no-drain`` is specified, a flush is issued without draining the request
297 If ``-n`` is specified, the native AIO backend is used if possible. On
306 Perform one or more modifications of the persistent bitmap *BITMAP*
307 in the disk image *FILENAME*. The various modifications are:
319 ``--merge`` to merge the contents of the *SOURCE* bitmap into *BITMAP*.
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``.
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
339 Only the formats ``qcow2``, ``qed``, ``parallels``, ``vhdx``, ``vmdk`` and
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:
347 Check completed, the image is (now) consistent
355 Checks are not supported by the image format
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.
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.
370 The image *FILENAME* is emptied after the operation has succeeded. If you do
372 *FILENAME* by specifying the ``-d`` flag.
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
377 chain). If *BASE* is not specified, the immediate backing file of the top
379 all images between *BASE* and the top image will be invalid and may return
381 the top image stays valid).
383 The rate limit for the commit process is specified by ``-r``.
387 Check if two images have the same content. You can compare images with
390 The format is probed unless you specify it by ``-f`` (used for
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
399 one image and is not allocated in the second one.
402 information that both images are same or the position of the first different
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
409 The following table summarizes all exit codes of the compare subcommand:
424 Convert the disk image *FILENAME* or a snapshot *SNAPSHOT_PARAM*
429 Only the formats ``qcow`` and ``qcow2`` support compression. The
434 growable format such as ``qcow``: the empty sectors are detected and
435 suppressed from the destination image.
437 *SPARSE_SIZE* indicates the consecutive number of bytes (defaults to 4k)
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
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.
448 If a relative path name is given, the backing file is looked up relative to
449 the directory containing *OUTPUT_FILENAME*.
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
462 the convert process (defaults to 8).
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
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*
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
481 If a relative path name is given, the backing file is looked up relative to
482 the directory containing *FILENAME*.
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
491 The size can also be specified using the *SIZE* option with ``-o``,
500 The data is by default read and written using blocks of 512 bytes but can be
504 The size syntax is similar to :manpage:`dd(1)`'s size syntax.
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,
514 the chain can be recursively enumerated by using the option ``--backing-chain``.
522 To enumerate information about each disk image in the above chain, starting from top to base, do:
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
532 ``--output=human`` reports the following information (for every image in the
536 The image file name
539 The image format
542 The size of the guest disk
545 How much space the image file occupies on the host file system (may be
550 Cluster size of the image format, if applicable
553 Whether the image is encrypted (only present if so)
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.
560 The backing file name, if present
563 The format of the backing file, if the image enforces it
569 Further information whose structure depends on the image format. This
570 section is a textual representation of the respective
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.
581 Two option formats are possible. The default format (``human``)
582 only dumps known-nonzero areas of the file. Known-zero parts of the
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:
595 means that 0x20000 (131072) bytes starting at offset 0 in the image are
602 The alternative format ``json`` will return an array of dictionaries
604 the ``start``, ``length``, ``offset`` fields;
607 - boolean field ``data``: true if the sectors contain actual data,
608 false if the sectors are either unallocated or stored as optimized
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*.
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
629 Calculate the file size required for a new image. This information
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``.
636 If the size *N* is given then act as if creating a new empty image file
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
644 The following fields are reported:
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.
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,
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
672 Changes the backing file of an image. Only the formats ``qcow2`` and
673 ``qed`` support changing the backing file.
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
681 If a relative path name is given, the backing file is looked up relative to
682 the directory containing *FILENAME*.
684 *CACHE* specifies the cache mode to be used for *FILENAME*, whereas
685 *SRC_CACHE* specifies the cache mode for reading backing files.
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*
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.
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
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.
712 This mode is useful for renaming or moving the backing file to
723 copying it, and that the ``modified.img`` guest has run so there
725 image called ``diff.qcow2`` that contains just the differences, do:
733 ``base.img + diff.qcow2`` contains the same information.
737 Change the disk image as if it had been created with *SIZE*.
740 partitioning tools inside the VM to reduce allocated file systems and partition
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
748 partitioning tools inside the VM to actually begin using the new space on the
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
765 Raw disk image format (default). This format has the advantage of
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
779 may not be zero, depending on the storage location.
783 QEMU image format, the most versatile format. Use it to have smaller
791 Determines the qcow2 version to use. ``compat=0.10`` uses the
794 newer understand (this is the default). Amongst others, this includes zero
801 Image format of the base image
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
815 If this option is set to ``on``, the image is encrypted with
818 The use of encryption in qcow and qcow2 images is considered to be
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
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.
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
834 the new file. The original file must then be securely erased
838 - Initialization vectors used to encrypt sectors are based on the
839 guest virtual sector number, instead of the host physical
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.
850 recommended to use an alternative encryption technology such as the
854 Changes the qcow2 cluster size (must be between 512 and
855 2M). Smaller cluster sizes can improve the image file size whereas
861 initially larger but can improve performance when the image needs
862 to grow. ``falloc`` and ``full`` preallocations are like the same
867 postponed with the goal of avoiding metadata I/O and improving
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)
877 If this option is set to ``on``, it will turn off COW of the file. It's
881 when the guest on the VM also using btrfs as file system. Turning
887 - For an empty file, add the NOCOW file attribute. That's what this
893 issue ``lsattr filename`` to check if the NOCOW flag is set or not
898 the qcow2 file will only contain the image's metadata.
900 Note: Data loss will occur if the given filename already exists when
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
907 If this option is set to ``on``, QEMU will always keep the external data
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
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
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
933 description of these formats, see the QEMU block drivers reference
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