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