1@example 2@c man begin SYNOPSIS 3@command{qemu-img} [@var{standard} @var{options}] @var{command} [@var{command} @var{options}] 4@c man end 5@end example 6 7@c man begin DESCRIPTION 8qemu-img allows you to create, convert and modify images offline. It can handle 9all image formats supported by QEMU. 10 11@b{Warning:} Never use qemu-img to modify images in use by a running virtual 12machine or any other process; this may destroy the image. Also, be aware that 13querying an image that is being modified by another process may encounter 14inconsistent state. 15@c man end 16 17@c man begin OPTIONS 18 19Standard options: 20@table @option 21@item -h, --help 22Display this help and exit 23@item -V, --version 24Display version information and exit 25@item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 26@findex --trace 27@include qemu-option-trace.texi 28@end table 29 30The following commands are supported: 31 32@include qemu-img-cmds.texi 33 34Command parameters: 35@table @var 36@item filename 37 is a disk image filename 38 39@item --object @var{objectdef} 40 41is a QEMU user creatable object definition. See the @code{qemu(1)} manual 42page for a description of the object properties. The most common object 43type is a @code{secret}, which is used to supply passwords and/or encryption 44keys. 45 46@item --image-opts 47 48Indicates that the @var{filename} parameter is to be interpreted as a 49full option string, not a plain filename. This parameter is mutually 50exclusive with the @var{-f} and @var{-F} parameters. 51 52@item fmt 53is the disk image format. It is guessed automatically in most cases. See below 54for a description of the supported disk formats. 55 56@item --backing-chain 57will enumerate information about backing files in a disk image chain. Refer 58below for further description. 59 60@item size 61is the disk image size in bytes. Optional suffixes @code{k} or @code{K} 62(kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M) 63and T (terabyte, 1024G) are supported. @code{b} is ignored. 64 65@item output_filename 66is the destination disk image filename 67 68@item output_fmt 69 is the destination format 70@item options 71is a comma separated list of format specific options in a 72name=value format. Use @code{-o ?} for an overview of the options supported 73by the used format or see the format descriptions below for details. 74@item snapshot_param 75is param used for internal snapshot, format is 76'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]' 77@item snapshot_id_or_name 78is deprecated, use snapshot_param instead 79 80@item -c 81indicates that target image must be compressed (qcow format only) 82@item -h 83with or without a command shows help and lists the supported formats 84@item -p 85display progress bar (compare, convert and rebase commands only). 86If the @var{-p} option is not used for a command that supports it, the 87progress is reported when the process receives a @code{SIGUSR1} signal. 88@item -q 89Quiet mode - do not print any output (except errors). There's no progress bar 90in case both @var{-q} and @var{-p} options are used. 91@item -S @var{size} 92indicates the consecutive number of bytes that must contain only zeros 93for qemu-img to create a sparse image during conversion. This value is rounded 94down to the nearest 512 bytes. You may use the common size suffixes like 95@code{k} for kilobytes. 96@item -t @var{cache} 97specifies the cache mode that should be used with the (destination) file. See 98the documentation of the emulator's @code{-drive cache=...} option for allowed 99values. 100@item -T @var{src_cache} 101specifies the cache mode that should be used with the source file(s). See 102the documentation of the emulator's @code{-drive cache=...} option for allowed 103values. 104@end table 105 106Parameters to snapshot subcommand: 107 108@table @option 109 110@item snapshot 111is the name of the snapshot to create, apply or delete 112@item -a 113applies a snapshot (revert disk to saved state) 114@item -c 115creates a snapshot 116@item -d 117deletes a snapshot 118@item -l 119lists all snapshots in the given image 120@end table 121 122Parameters to compare subcommand: 123 124@table @option 125 126@item -f 127First image format 128@item -F 129Second image format 130@item -s 131Strict mode - fail on different image size or sector allocation 132@end table 133 134Parameters to convert subcommand: 135 136@table @option 137 138@item -n 139Skip the creation of the target volume 140@end table 141 142Parameters to dd subcommand: 143 144@table @option 145 146@item bs=@var{block_size} 147defines the block size 148@item count=@var{blocks} 149sets the number of input blocks to copy 150@item if=@var{input} 151sets the input file 152@item of=@var{output} 153sets the output file 154@item skip=@var{blocks} 155sets the number of input blocks to skip 156@end table 157 158Command description: 159 160@table @option 161@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] @var{filename} 162 163Run a simple sequential I/O benchmark on the specified image. If @code{-w} is 164specified, a write test is performed, otherwise a read test is performed. 165 166A total number of @var{count} I/O requests is performed, each @var{buffer_size} 167bytes in size, and with @var{depth} requests in parallel. The first request 168starts at the position given by @var{offset}, each following request increases 169the current position by @var{step_size}. If @var{step_size} is not given, 170@var{buffer_size} is used for its value. 171 172If @var{flush_interval} is specified for a write test, the request queue is 173drained and a flush is issued before new writes are made whenever the number of 174remaining requests is a multiple of @var{flush_interval}. If additionally 175@code{--no-drain} is specified, a flush is issued without draining the request 176queue first. 177 178If @code{-n} is specified, the native AIO backend is used if possible. On 179Linux, this option only works if @code{-t none} or @code{-t directsync} is 180specified as well. 181 182For write tests, by default a buffer filled with zeros is written. This can be 183overridden with a pattern byte specified by @var{pattern}. 184 185@item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] @var{filename} 186 187Perform a consistency check on the disk image @var{filename}. The command can 188output in the format @var{ofmt} which is either @code{human} or @code{json}. 189 190If @code{-r} is specified, qemu-img tries to repair any inconsistencies found 191during the check. @code{-r leaks} repairs only cluster leaks, whereas 192@code{-r all} fixes all kinds of errors, with a higher risk of choosing the 193wrong fix or hiding corruption that has already occurred. 194 195Only the formats @code{qcow2}, @code{qed} and @code{vdi} support 196consistency checks. 197 198In case the image does not have any inconsistencies, check exits with @code{0}. 199Other exit codes indicate the kind of inconsistency found or if another error 200occurred. The following table summarizes all exit codes of the check subcommand: 201 202@table @option 203 204@item 0 205Check completed, the image is (now) consistent 206@item 1 207Check not completed because of internal errors 208@item 2 209Check completed, image is corrupted 210@item 3 211Check completed, image has leaked clusters, but is not corrupted 212@item 63 213Checks are not supported by the image format 214 215@end table 216 217If @code{-r} is specified, exit codes representing the image state refer to the 218state after (the attempt at) repairing it. That is, a successful @code{-r all} 219will yield the exit code 0, independently of the image state before. 220 221@item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}] 222 223Create the new disk image @var{filename} of size @var{size} and format 224@var{fmt}. Depending on the file format, you can add one or more @var{options} 225that enable additional features of this format. 226 227If the option @var{backing_file} is specified, then the image will record 228only the differences from @var{backing_file}. No size needs to be specified in 229this case. @var{backing_file} will never be modified unless you use the 230@code{commit} monitor command (or qemu-img commit). 231 232The size can also be specified using the @var{size} option with @code{-o}, 233it doesn't need to be specified separately in this case. 234 235@item commit [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename} 236 237Commit the changes recorded in @var{filename} in its base image or backing file. 238If the backing file is smaller than the snapshot, then the backing file will be 239resized to be the same size as the snapshot. If the snapshot is smaller than 240the backing file, the backing file will not be truncated. If you want the 241backing file to match the size of the smaller snapshot, you can safely truncate 242it yourself once the commit operation successfully completes. 243 244The image @var{filename} is emptied after the operation has succeeded. If you do 245not need @var{filename} afterwards and intend to drop it, you may skip emptying 246@var{filename} by specifying the @code{-d} flag. 247 248If the backing chain of the given image file @var{filename} has more than one 249layer, the backing file into which the changes will be committed may be 250specified as @var{base} (which has to be part of @var{filename}'s backing 251chain). If @var{base} is not specified, the immediate backing file of the top 252image (which is @var{filename}) will be used. For reasons of consistency, 253explicitly specifying @var{base} will always imply @code{-d} (since emptying an 254image after committing to an indirect backing file would lead to different data 255being read from the image due to content in the intermediate backing chain 256overruling the commit target). 257 258@item compare [-f @var{fmt}] [-F @var{fmt}] [-T @var{src_cache}] [-p] [-s] [-q] @var{filename1} @var{filename2} 259 260Check if two images have the same content. You can compare images with 261different format or settings. 262 263The format is probed unless you specify it by @var{-f} (used for 264@var{filename1}) and/or @var{-F} (used for @var{filename2}) option. 265 266By default, images with different size are considered identical if the larger 267image contains only unallocated and/or zeroed sectors in the area after the end 268of the other image. In addition, if any sector is not allocated in one image 269and contains only zero bytes in the second one, it is evaluated as equal. You 270can use Strict mode by specifying the @var{-s} option. When compare runs in 271Strict mode, it fails in case image size differs or a sector is allocated in 272one image and is not allocated in the second one. 273 274By default, compare prints out a result message. This message displays 275information that both images are same or the position of the first different 276byte. In addition, result message can report different image size in case 277Strict mode is used. 278 279Compare exits with @code{0} in case the images are equal and with @code{1} 280in case the images differ. Other exit codes mean an error occurred during 281execution and standard error output should contain an error message. 282The following table sumarizes all exit codes of the compare subcommand: 283 284@table @option 285 286@item 0 287Images are identical 288@item 1 289Images differ 290@item 2 291Error on opening an image 292@item 3 293Error on checking a sector allocation 294@item 4 295Error on reading data 296 297@end table 298 299@item convert [-c] [-p] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_id_or_name}] [-l @var{snapshot_param}] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename} 300 301Convert the disk image @var{filename} or a snapshot @var{snapshot_param}(@var{snapshot_id_or_name} is deprecated) 302to disk image @var{output_filename} using format @var{output_fmt}. It can be optionally compressed (@code{-c} 303option) or use any format specific options like encryption (@code{-o} option). 304 305Only the formats @code{qcow} and @code{qcow2} support compression. The 306compression is read-only. It means that if a compressed sector is 307rewritten, then it is rewritten as uncompressed data. 308 309Image conversion is also useful to get smaller image when using a 310growable format such as @code{qcow}: the empty sectors are detected and 311suppressed from the destination image. 312 313@var{sparse_size} indicates the consecutive number of bytes (defaults to 4k) 314that must contain only zeros for qemu-img to create a sparse image during 315conversion. If @var{sparse_size} is 0, the source will not be scanned for 316unallocated or zero sectors, and the destination image will always be 317fully allocated. 318 319You can use the @var{backing_file} option to force the output image to be 320created as a copy on write image of the specified base image; the 321@var{backing_file} should have the same content as the input's base image, 322however the path, image format, etc may differ. 323 324If the @code{-n} option is specified, the target volume creation will be 325skipped. This is useful for formats such as @code{rbd} if the target 326volume has already been created with site specific options that cannot 327be supplied through qemu-img. 328 329@item dd [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output} 330 331Dd copies from @var{input} file to @var{output} file converting it from 332@var{fmt} format to @var{output_fmt} format. 333 334The data is by default read and written using blocks of 512 bytes but can be 335modified by specifying @var{block_size}. If count=@var{blocks} is specified 336dd will stop reading input after reading @var{blocks} input blocks. 337 338The size syntax is similar to dd(1)'s size syntax. 339 340@item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename} 341 342Give information about the disk image @var{filename}. Use it in 343particular to know the size reserved on disk which can be different 344from the displayed size. If VM snapshots are stored in the disk image, 345they are displayed too. The command can output in the format @var{ofmt} 346which is either @code{human} or @code{json}. 347 348If a disk image has a backing file chain, information about each disk image in 349the chain can be recursively enumerated by using the option @code{--backing-chain}. 350 351For instance, if you have an image chain like: 352 353@example 354base.qcow2 <- snap1.qcow2 <- snap2.qcow2 355@end example 356 357To enumerate information about each disk image in the above chain, starting from top to base, do: 358 359@example 360qemu-img info --backing-chain snap2.qcow2 361@end example 362 363@item map [-f @var{fmt}] [--output=@var{ofmt}] @var{filename} 364 365Dump the metadata of image @var{filename} and its backing file chain. 366In particular, this commands dumps the allocation state of every sector 367of @var{filename}, together with the topmost file that allocates it in 368the backing file chain. 369 370Two option formats are possible. The default format (@code{human}) 371only dumps known-nonzero areas of the file. Known-zero parts of the 372file are omitted altogether, and likewise for parts that are not allocated 373throughout the chain. @command{qemu-img} output will identify a file 374from where the data can be read, and the offset in the file. Each line 375will include four fields, the first three of which are hexadecimal 376numbers. For example the first line of: 377@example 378Offset Length Mapped to File 3790 0x20000 0x50000 /tmp/overlay.qcow2 3800x100000 0x10000 0x95380000 /tmp/backing.qcow2 381@end example 382@noindent 383means that 0x20000 (131072) bytes starting at offset 0 in the image are 384available in /tmp/overlay.qcow2 (opened in @code{raw} format) starting 385at offset 0x50000 (327680). Data that is compressed, encrypted, or 386otherwise not available in raw format will cause an error if @code{human} 387format is in use. Note that file names can include newlines, thus it is 388not safe to parse this output format in scripts. 389 390The alternative format @code{json} will return an array of dictionaries 391in JSON format. It will include similar information in 392the @code{start}, @code{length}, @code{offset} fields; 393it will also include other more specific information: 394@itemize @minus 395@item 396whether the sectors contain actual data or not (boolean field @code{data}; 397if false, the sectors are either unallocated or stored as optimized 398all-zero clusters); 399 400@item 401whether the data is known to read as zero (boolean field @code{zero}); 402 403@item 404in order to make the output shorter, the target file is expressed as 405a @code{depth}; for example, a depth of 2 refers to the backing file 406of the backing file of @var{filename}. 407@end itemize 408 409In JSON format, the @code{offset} field is optional; it is absent in 410cases where @code{human} format would omit the entry or exit with an error. 411If @code{data} is false and the @code{offset} field is present, the 412corresponding sectors in the file are not yet in use, but they are 413preallocated. 414 415For more information, consult @file{include/block/block.h} in QEMU's 416source code. 417 418@item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename} 419 420List, apply, create or delete snapshots in image @var{filename}. 421 422@item rebase [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename} 423 424Changes the backing file of an image. Only the formats @code{qcow2} and 425@code{qed} support changing the backing file. 426 427The backing file is changed to @var{backing_file} and (if the image format of 428@var{filename} supports this) the backing file format is changed to 429@var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty 430string), then the image is rebased onto no backing file (i.e. it will exist 431independently of any backing file). 432 433@var{cache} specifies the cache mode to be used for @var{filename}, whereas 434@var{src_cache} specifies the cache mode for reading backing files. 435 436There are two different modes in which @code{rebase} can operate: 437@table @option 438@item Safe mode 439This is the default mode and performs a real rebase operation. The new backing 440file may differ from the old one and qemu-img rebase will take care of keeping 441the guest-visible content of @var{filename} unchanged. 442 443In order to achieve this, any clusters that differ between @var{backing_file} 444and the old backing file of @var{filename} are merged into @var{filename} 445before actually changing the backing file. 446 447Note that the safe mode is an expensive operation, comparable to converting 448an image. It only works if the old backing file still exists. 449 450@item Unsafe mode 451qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the 452backing file name and format of @var{filename} is changed without any checks 453on the file contents. The user must take care of specifying the correct new 454backing file, or the guest-visible content of the image will be corrupted. 455 456This mode is useful for renaming or moving the backing file to somewhere else. 457It can be used without an accessible old backing file, i.e. you can use it to 458fix an image whose backing file has already been moved/renamed. 459@end table 460 461You can use @code{rebase} to perform a ``diff'' operation on two 462disk images. This can be useful when you have copied or cloned 463a guest, and you want to get back to a thin image on top of a 464template or base image. 465 466Say that @code{base.img} has been cloned as @code{modified.img} by 467copying it, and that the @code{modified.img} guest has run so there 468are now some changes compared to @code{base.img}. To construct a thin 469image called @code{diff.qcow2} that contains just the differences, do: 470 471@example 472qemu-img create -f qcow2 -b modified.img diff.qcow2 473qemu-img rebase -b base.img diff.qcow2 474@end example 475 476At this point, @code{modified.img} can be discarded, since 477@code{base.img + diff.qcow2} contains the same information. 478 479@item resize @var{filename} [+ | -]@var{size} 480 481Change the disk image as if it had been created with @var{size}. 482 483Before using this command to shrink a disk image, you MUST use file system and 484partitioning tools inside the VM to reduce allocated file systems and partition 485sizes accordingly. Failure to do so will result in data loss! 486 487After using this command to grow a disk image, you must use file system and 488partitioning tools inside the VM to actually begin using the new space on the 489device. 490 491@item amend [-p] [-f @var{fmt}] [-t @var{cache}] -o @var{options} @var{filename} 492 493Amends the image format specific @var{options} for the image file 494@var{filename}. Not all file formats support this operation. 495@end table 496@c man end 497 498@ignore 499@c man begin NOTES 500Supported image file formats: 501 502@table @option 503@item raw 504 505Raw disk image format (default). This format has the advantage of 506being simple and easily exportable to all other emulators. If your 507file system supports @emph{holes} (for example in ext2 or ext3 on 508Linux or NTFS on Windows), then only the written sectors will reserve 509space. Use @code{qemu-img info} to know the real size used by the 510image or @code{ls -ls} on Unix/Linux. 511 512Supported options: 513@table @code 514@item preallocation 515Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}). 516@code{falloc} mode preallocates space for image by calling posix_fallocate(). 517@code{full} mode preallocates space for image by writing zeros to underlying 518storage. 519@end table 520 521@item qcow2 522QEMU image format, the most versatile format. Use it to have smaller 523images (useful if your filesystem does not supports holes, for example 524on Windows), optional AES encryption, zlib based compression and 525support of multiple VM snapshots. 526 527Supported options: 528@table @code 529@item compat 530Determines the qcow2 version to use. @code{compat=0.10} uses the 531traditional image format that can be read by any QEMU since 0.10. 532@code{compat=1.1} enables image format extensions that only QEMU 1.1 and 533newer understand (this is the default). Amongst others, this includes zero 534clusters, which allow efficient copy-on-read for sparse images. 535 536@item backing_file 537File name of a base image (see @option{create} subcommand) 538@item backing_fmt 539Image format of the base image 540@item encryption 541If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC. 542 543The use of encryption in qcow and qcow2 images is considered to be flawed by 544modern cryptography standards, suffering from a number of design problems: 545 546@itemize @minus 547@item The AES-CBC cipher is used with predictable initialization vectors based 548on the sector number. This makes it vulnerable to chosen plaintext attacks 549which can reveal the existence of encrypted data. 550@item The user passphrase is directly used as the encryption key. A poorly 551chosen or short passphrase will compromise the security of the encryption. 552@item In the event of the passphrase being compromised there is no way to 553change the passphrase to protect data in any qcow images. The files must 554be cloned, using a different encryption passphrase in the new file. The 555original file must then be securely erased using a program like shred, 556though even this is ineffective with many modern storage technologies. 557@end itemize 558 559Use of qcow / qcow2 encryption is thus strongly discouraged. Users are 560recommended to use an alternative encryption technology such as the 561Linux dm-crypt / LUKS system. 562 563@item cluster_size 564Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster 565sizes can improve the image file size whereas larger cluster sizes generally 566provide better performance. 567 568@item preallocation 569Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc}, 570@code{full}). An image with preallocated metadata is initially larger but can 571improve performance when the image needs to grow. @code{falloc} and @code{full} 572preallocations are like the same options of @code{raw} format, but sets up 573metadata also. 574 575@item lazy_refcounts 576If this option is set to @code{on}, reference count updates are postponed with 577the goal of avoiding metadata I/O and improving performance. This is 578particularly interesting with @option{cache=writethrough} which doesn't batch 579metadata updates. The tradeoff is that after a host crash, the reference count 580tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img 581check -r all} is required, which may take some time. 582 583This option can only be enabled if @code{compat=1.1} is specified. 584 585@item nocow 586If this option is set to @code{on}, it will turn off COW of the file. It's only 587valid on btrfs, no effect on other file systems. 588 589Btrfs has low performance when hosting a VM image file, even more when the guest 590on the VM also using btrfs as file system. Turning off COW is a way to mitigate 591this bad performance. Generally there are two ways to turn off COW on btrfs: 592a) Disable it by mounting with nodatacow, then all newly created files will be 593NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option 594does. 595 596Note: this option is only valid to new or empty files. If there is an existing 597file which is COW and has data blocks already, it couldn't be changed to NOCOW 598by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if 599the NOCOW flag is set or not (Capital 'C' is NOCOW flag). 600 601@end table 602 603@item Other 604QEMU also supports various other image file formats for compatibility with 605older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), VHDX, 606qcow1 and QED. For a full list of supported formats see @code{qemu-img --help}. 607For a more detailed description of these formats, see the QEMU Emulation User 608Documentation. 609 610The main purpose of the block drivers for these formats is image conversion. 611For running VMs, it is recommended to convert the disk images to either raw or 612qcow2 in order to achieve good performance. 613@end table 614 615 616@c man end 617 618@setfilename qemu-img 619@settitle QEMU disk image utility 620 621@c man begin SEEALSO 622The HTML documentation of QEMU for more precise information and Linux 623user mode emulator invocation. 624@c man end 625 626@c man begin AUTHOR 627Fabrice Bellard 628@c man end 629 630@end ignore 631