1QEMU-IMG.1(1)                                                    QEMU-IMG.1(1)
2
3
4

NAME

6       qemu-img - QEMU disk image utility
7

SYNOPSIS

9       qemu-img [standard options] command [command options]
10

DESCRIPTION

12       qemu-img allows you to create, convert and modify images offline. It
13       can handle all image formats supported by QEMU.
14
15       Warning: Never use qemu-img to modify images in use by a running
16       virtual machine or any other process; this may destroy the image. Also,
17       be aware that querying an image that is being modified by another
18       process may encounter inconsistent state.
19

OPTIONS

21       Standard options:
22
23       -h, --help
24           Display this help and exit
25
26       -V, --version
27           Display version information and exit
28
29       -T, --trace [[enable=]pattern][,events=file][,file=file]
30           Specify tracing options.
31
32           [enable=]pattern
33               Immediately enable events matching pattern (either event name
34               or a globbing pattern).  This option is only available if QEMU
35               has been compiled with the simple, log or ftrace tracing
36               backend.  To specify multiple events or patterns, specify the
37               -trace option multiple times.
38
39               Use "-trace help" to print a list of names of trace points.
40
41           events=file
42               Immediately enable events listed in file.  The file must
43               contain one event name (as listed in the trace-events-all file)
44               per line; globbing patterns are accepted too.  This option is
45               only available if QEMU has been compiled with the simple, log
46               or ftrace tracing backend.
47
48           file=file
49               Log output traces to file.  This option is only available if
50               QEMU has been compiled with the simple tracing backend.
51
52       The following commands are supported:
53
54       amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt] [-t cache]
55       -o options filename
56       bench [-c count] [-d depth] [-f fmt] [--flush-interval=flush_interval]
57       [-n] [--no-drain] [-o offset] [--pattern=pattern] [-q] [-s buffer_size]
58       [-S step_size] [-t cache] [-w] [-U] filename
59       check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt]
60       [-r [leaks | all]] [-T src_cache] [-U] filename
61       commit [--object objectdef] [--image-opts] [-q] [-f fmt] [-t cache] [-b
62       base] [-d] [-p] filename
63       compare [--object objectdef] [--image-opts] [-f fmt] [-F fmt] [-T
64       src_cache] [-p] [-q] [-s] [-U] filename1 filename2
65       convert [--object objectdef] [--image-opts] [--target-image-opts] [-U]
66       [-C] [-c] [-p] [-q] [-n] [-f fmt] [-t cache] [-T src_cache] [-O
67       output_fmt] [-B backing_file] [-o options] [-l snapshot_param] [-S
68       sparse_size] [-m num_coroutines] [-W] [--salvage] filename [filename2
69       [...]] output_filename
70       create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F
71       backing_fmt] [-u] [-o options] filename [size]
72       dd [--image-opts] [-U] [-f fmt] [-O output_fmt] [bs=block_size]
73       [count=blocks] [skip=blocks] if=input of=output
74       info [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt]
75       [--backing-chain] [-U] filename
76       map [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt] [-U]
77       filename
78       measure [--output=ofmt] [-O output_fmt] [-o options] [--size N |
79       [--object objectdef] [--image-opts] [-f fmt] [-l snapshot_param]
80       filename]
81       snapshot [--object objectdef] [--image-opts] [-U] [-q] [-l | -a
82       snapshot | -c snapshot | -d snapshot] filename
83       rebase [--object objectdef] [--image-opts] [-U] [-q] [-f fmt] [-t
84       cache] [-T src_cache] [-p] [-u] -b backing_file [-F backing_fmt]
85       filename
86       resize [--object objectdef] [--image-opts] [-f fmt]
87       [--preallocation=prealloc] [-q] [--shrink] filename [+ | -]size
88
89       Command parameters:
90
91       filename
92           is a disk image filename
93
94       fmt is the disk image format. It is guessed automatically in most
95           cases. See below for a description of the supported disk formats.
96
97       size
98           is the disk image size in bytes. Optional suffixes "k" or "K"
99           (kilobyte, 1024) "M" (megabyte, 1024k) and "G" (gigabyte, 1024M)
100           and T (terabyte, 1024G) are supported.  "b" is ignored.
101
102       output_filename
103           is the destination disk image filename
104
105       output_fmt
106           is the destination format
107
108       options
109           is a comma separated list of format specific options in a
110           name=value format. Use "-o ?" for an overview of the options
111           supported by the used format or see the format descriptions below
112           for details.
113
114       snapshot_param
115           is param used for internal snapshot, format is
116           'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'
117
118       --object objectdef
119           is a QEMU user creatable object definition. See the qemu(1) manual
120           page for a description of the object properties. The most common
121           object type is a "secret", which is used to supply passwords and/or
122           encryption keys.
123
124       --image-opts
125           Indicates that the source filename parameter is to be interpreted
126           as a full option string, not a plain filename. This parameter is
127           mutually exclusive with the -f parameter.
128
129       --target-image-opts
130           Indicates that the output_filename parameter(s) are to be
131           interpreted as a full option string, not a plain filename. This
132           parameter is mutually exclusive with the -O parameters. It is
133           currently required to also use the -n parameter to skip image
134           creation. This restriction may be relaxed in a future release.
135
136       --force-share (-U)
137           If specified, "qemu-img" will open the image in shared mode,
138           allowing other QEMU processes to open it in write mode. For
139           example, this can be used to get the image information (with 'info'
140           subcommand) when the image is used by a running guest.  Note that
141           this could produce inconsistent results because of concurrent
142           metadata changes, etc. This option is only allowed when opening
143           images in read-only mode.
144
145       --backing-chain
146           will enumerate information about backing files in a disk image
147           chain. Refer below for further description.
148
149       -c  indicates that target image must be compressed (qcow format only)
150
151       -h  with or without a command shows help and lists the supported
152           formats
153
154       -p  display progress bar (compare, convert and rebase commands only).
155           If the -p option is not used for a command that supports it, the
156           progress is reported when the process receives a "SIGUSR1" or
157           "SIGINFO" signal.
158
159       -q  Quiet mode - do not print any output (except errors). There's no
160           progress bar in case both -q and -p options are used.
161
162       -S size
163           indicates the consecutive number of bytes that must contain only
164           zeros for qemu-img to create a sparse image during conversion. This
165           value is rounded down to the nearest 512 bytes. You may use the
166           common size suffixes like "k" for kilobytes.
167
168       -t cache
169           specifies the cache mode that should be used with the (destination)
170           file. See the documentation of the emulator's "-drive cache=..."
171           option for allowed values.
172
173       -T src_cache
174           specifies the cache mode that should be used with the source
175           file(s). See the documentation of the emulator's "-drive cache=..."
176           option for allowed values.
177
178       Parameters to snapshot subcommand:
179
180       snapshot
181           is the name of the snapshot to create, apply or delete
182
183       -a  applies a snapshot (revert disk to saved state)
184
185       -c  creates a snapshot
186
187       -d  deletes a snapshot
188
189       -l  lists all snapshots in the given image
190
191       Parameters to compare subcommand:
192
193       -f  First image format
194
195       -F  Second image format
196
197       -s  Strict mode - fail on different image size or sector allocation
198
199       Parameters to convert subcommand:
200
201       -n  Skip the creation of the target volume
202
203       -m  Number of parallel coroutines for the convert process
204
205       -W  Allow out-of-order writes to the destination. This option improves
206           performance, but is only recommended for preallocated devices like
207           host devices or other raw block devices.
208
209       -C  Try to use copy offloading to move data from source image to
210           target. This may improve performance if the data is remote, such as
211           with NFS or iSCSI backends, but will not automatically sparsify
212           zero sectors, and may result in a fully allocated target image
213           depending on the host support for getting allocation information.
214
215       --salvage
216           Try to ignore I/O errors when reading.  Unless in quiet mode
217           ("-q"), errors will still be printed.  Areas that cannot be read
218           from the source will be treated as containing only zeroes.
219
220       Parameters to dd subcommand:
221
222       bs=block_size
223           defines the block size
224
225       count=blocks
226           sets the number of input blocks to copy
227
228       if=input
229           sets the input file
230
231       of=output
232           sets the output file
233
234       skip=blocks
235           sets the number of input blocks to skip
236
237       Command description:
238
239       amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt] [-t cache]
240       -o options filename
241           Amends the image format specific options for the image file
242           filename. Not all file formats support this operation.
243
244       bench [-c count] [-d depth] [-f fmt] [--flush-interval=flush_interval]
245       [-n] [--no-drain] [-o offset] [--pattern=pattern] [-q] [-s buffer_size]
246       [-S step_size] [-t cache] [-w] [-U] filename
247           Run a simple sequential I/O benchmark on the specified image. If
248           "-w" is specified, a write test is performed, otherwise a read test
249           is performed.
250
251           A total number of count I/O requests is performed, each buffer_size
252           bytes in size, and with depth requests in parallel. The first
253           request starts at the position given by offset, each following
254           request increases the current position by step_size. If step_size
255           is not given, buffer_size is used for its value.
256
257           If flush_interval is specified for a write test, the request queue
258           is drained and a flush is issued before new writes are made
259           whenever the number of remaining requests is a multiple of
260           flush_interval. If additionally "--no-drain" is specified, a flush
261           is issued without draining the request queue first.
262
263           If "-n" is specified, the native AIO backend is used if possible.
264           On Linux, this option only works if "-t none" or "-t directsync" is
265           specified as well.
266
267           For write tests, by default a buffer filled with zeros is written.
268           This can be overridden with a pattern byte specified by pattern.
269
270       check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt]
271       [-r [leaks | all]] [-T src_cache] [-U] filename
272           Perform a consistency check on the disk image filename. The command
273           can output in the format ofmt which is either "human" or "json".
274           The JSON output is an object of QAPI type "ImageCheck".
275
276           If "-r" is specified, qemu-img tries to repair any inconsistencies
277           found during the check. "-r leaks" repairs only cluster leaks,
278           whereas "-r all" fixes all kinds of errors, with a higher risk of
279           choosing the wrong fix or hiding corruption that has already
280           occurred.
281
282           Only the formats "qcow2", "qed" and "vdi" support consistency
283           checks.
284
285           In case the image does not have any inconsistencies, check exits
286           with 0.  Other exit codes indicate the kind of inconsistency found
287           or if another error occurred. The following table summarizes all
288           exit codes of the check subcommand:
289
290           0   Check completed, the image is (now) consistent
291
292           1   Check not completed because of internal errors
293
294           2   Check completed, image is corrupted
295
296           3   Check completed, image has leaked clusters, but is not
297               corrupted
298
299           63  Checks are not supported by the image format
300
301           If "-r" is specified, exit codes representing the image state refer
302           to the state after (the attempt at) repairing it. That is, a
303           successful "-r all" will yield the exit code 0, independently of
304           the image state before.
305
306       commit [--object objectdef] [--image-opts] [-q] [-f fmt] [-t cache] [-b
307       base] [-d] [-p] filename
308           Commit the changes recorded in filename in its base image or
309           backing file.  If the backing file is smaller than the snapshot,
310           then the backing file will be resized to be the same size as the
311           snapshot.  If the snapshot is smaller than the backing file, the
312           backing file will not be truncated.  If you want the backing file
313           to match the size of the smaller snapshot, you can safely truncate
314           it yourself once the commit operation successfully completes.
315
316           The image filename is emptied after the operation has succeeded. If
317           you do not need filename afterwards and intend to drop it, you may
318           skip emptying filename by specifying the "-d" flag.
319
320           If the backing chain of the given image file filename has more than
321           one layer, the backing file into which the changes will be
322           committed may be specified as base (which has to be part of
323           filename's backing chain). If base is not specified, the immediate
324           backing file of the top image (which is filename) will be used.
325           Note that after a commit operation all images between base and the
326           top image will be invalid and may return garbage data when read.
327           For this reason, "-b" implies "-d" (so that the top image stays
328           valid).
329
330       compare [--object objectdef] [--image-opts] [-f fmt] [-F fmt] [-T
331       src_cache] [-p] [-q] [-s] [-U] filename1 filename2
332           Check if two images have the same content. You can compare images
333           with different format or settings.
334
335           The format is probed unless you specify it by -f (used for
336           filename1) and/or -F (used for filename2) option.
337
338           By default, images with different size are considered identical if
339           the larger image contains only unallocated and/or zeroed sectors in
340           the area after the end of the other image. In addition, if any
341           sector is not allocated in one image and contains only zero bytes
342           in the second one, it is evaluated as equal. You can use Strict
343           mode by specifying the -s option. When compare runs in Strict mode,
344           it fails in case image size differs or a sector is allocated in one
345           image and is not allocated in the second one.
346
347           By default, compare prints out a result message. This message
348           displays information that both images are same or the position of
349           the first different byte. In addition, result message can report
350           different image size in case Strict mode is used.
351
352           Compare exits with 0 in case the images are equal and with 1 in
353           case the images differ. Other exit codes mean an error occurred
354           during execution and standard error output should contain an error
355           message.  The following table sumarizes all exit codes of the
356           compare subcommand:
357
358           0   Images are identical
359
360           1   Images differ
361
362           2   Error on opening an image
363
364           3   Error on checking a sector allocation
365
366           4   Error on reading data
367
368       convert [--object objectdef] [--image-opts] [--target-image-opts] [-U]
369       [-C] [-c] [-p] [-q] [-n] [-f fmt] [-t cache] [-T src_cache] [-O
370       output_fmt] [-B backing_file] [-o options] [-l snapshot_param] [-S
371       sparse_size] [-m num_coroutines] [-W] filename [filename2 [...]]
372       output_filename
373           Convert the disk image filename or a snapshot snapshot_param to
374           disk image output_filename using format output_fmt. It can be
375           optionally compressed ("-c" option) or use any format specific
376           options like encryption ("-o" option).
377
378           Only the formats "qcow" and "qcow2" support compression. The
379           compression is read-only. It means that if a compressed sector is
380           rewritten, then it is rewritten as uncompressed data.
381
382           Image conversion is also useful to get smaller image when using a
383           growable format such as "qcow": the empty sectors are detected and
384           suppressed from the destination image.
385
386           sparse_size indicates the consecutive number of bytes (defaults to
387           4k) that must contain only zeros for qemu-img to create a sparse
388           image during conversion. If sparse_size is 0, the source will not
389           be scanned for unallocated or zero sectors, and the destination
390           image will always be fully allocated.
391
392           You can use the backing_file option to force the output image to be
393           created as a copy on write image of the specified base image; the
394           backing_file should have the same content as the input's base
395           image, however the path, image format, etc may differ.
396
397           If a relative path name is given, the backing file is looked up
398           relative to the directory containing output_filename.
399
400           If the "-n" option is specified, the target volume creation will be
401           skipped. This is useful for formats such as "rbd" if the target
402           volume has already been created with site specific options that
403           cannot be supplied through qemu-img.
404
405           Out of order writes can be enabled with "-W" to improve
406           performance.  This is only recommended for preallocated devices
407           like host devices or other raw block devices. Out of order write
408           does not work in combination with creating compressed images.
409
410           num_coroutines specifies how many coroutines work in parallel
411           during the convert process (defaults to 8).
412
413       create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F
414       backing_fmt] [-u] [-o options] filename [size]
415           Create the new disk image filename of size size and format fmt.
416           Depending on the file format, you can add one or more options that
417           enable additional features of this format.
418
419           If the option backing_file is specified, then the image will record
420           only the differences from backing_file. No size needs to be
421           specified in this case. backing_file will never be modified unless
422           you use the "commit" monitor command (or qemu-img commit).
423
424           If a relative path name is given, the backing file is looked up
425           relative to the directory containing filename.
426
427           Note that a given backing file will be opened to check that it is
428           valid. Use the "-u" option to enable unsafe backing file mode,
429           which means that the image will be created even if the associated
430           backing file cannot be opened. A matching backing file must be
431           created or additional options be used to make the backing file
432           specification valid when you want to use an image created this way.
433
434           The size can also be specified using the size option with "-o", it
435           doesn't need to be specified separately in this case.
436
437       dd [--image-opts] [-U] [-f fmt] [-O output_fmt] [bs=block_size]
438       [count=blocks] [skip=blocks] if=input of=output
439           Dd copies from input file to output file converting it from fmt
440           format to output_fmt format.
441
442           The data is by default read and written using blocks of 512 bytes
443           but can be modified by specifying block_size. If count=blocks is
444           specified dd will stop reading input after reading blocks input
445           blocks.
446
447           The size syntax is similar to dd(1)'s size syntax.
448
449       info [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt]
450       [--backing-chain] [-U] filename
451           Give information about the disk image filename. Use it in
452           particular to know the size reserved on disk which can be different
453           from the displayed size. If VM snapshots are stored in the disk
454           image, they are displayed too.
455
456           If a disk image has a backing file chain, information about each
457           disk image in the chain can be recursively enumerated by using the
458           option "--backing-chain".
459
460           For instance, if you have an image chain like:
461
462                   base.qcow2 <- snap1.qcow2 <- snap2.qcow2
463
464           To enumerate information about each disk image in the above chain,
465           starting from top to base, do:
466
467                   qemu-img info --backing-chain snap2.qcow2
468
469           The command can output in the format ofmt which is either "human"
470           or "json".  The JSON output is an object of QAPI type "ImageInfo";
471           with "--backing-chain", it is an array of "ImageInfo" objects.
472
473           "--output=human" reports the following information (for every image
474           in the chain):
475
476           image
477               The image file name
478
479           file format
480               The image format
481
482           virtual size
483               The size of the guest disk
484
485           disk size
486               How much space the image file occupies on the host file system
487               (may be shown as 0 if this information is unavailable, e.g.
488               because there is no file system)
489
490           cluster_size
491               Cluster size of the image format, if applicable
492
493           encrypted
494               Whether the image is encrypted (only present if so)
495
496           cleanly shut down
497               This is shown as "no" if the image is dirty and will have to be
498               auto-repaired the next time it is opened in qemu.
499
500           backing file
501               The backing file name, if present
502
503           backing file format
504               The format of the backing file, if the image enforces it
505
506           Snapshot list
507               A list of all internal snapshots
508
509           Format specific information
510               Further information whose structure depends on the image
511               format.  This section is a textual representation of the
512               respective "ImageInfoSpecific*" QAPI object (e.g.
513               "ImageInfoSpecificQCow2" for qcow2 images).
514
515       map [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt] [-U]
516       filename
517           Dump the metadata of image filename and its backing file chain.  In
518           particular, this commands dumps the allocation state of every
519           sector of filename, together with the topmost file that allocates
520           it in the backing file chain.
521
522           Two option formats are possible.  The default format ("human") only
523           dumps known-nonzero areas of the file.  Known-zero parts of the
524           file are omitted altogether, and likewise for parts that are not
525           allocated throughout the chain.  qemu-img output will identify a
526           file from where the data can be read, and the offset in the file.
527           Each line will include four fields, the first three of which are
528           hexadecimal numbers.  For example the first line of:
529
530                   Offset          Length          Mapped to       File
531                   0               0x20000         0x50000         /tmp/overlay.qcow2
532                   0x100000        0x10000         0x95380000      /tmp/backing.qcow2
533
534           means that 0x20000 (131072) bytes starting at offset 0 in the image
535           are available in /tmp/overlay.qcow2 (opened in "raw" format)
536           starting at offset 0x50000 (327680).  Data that is compressed,
537           encrypted, or otherwise not available in raw format will cause an
538           error if "human" format is in use.  Note that file names can
539           include newlines, thus it is not safe to parse this output format
540           in scripts.
541
542           The alternative format "json" will return an array of dictionaries
543           in JSON format.  It will include similar information in the
544           "start", "length", "offset" fields; it will also include other more
545           specific information:
546
547           -   whether the sectors contain actual data or not (boolean field
548               "data"; if false, the sectors are either unallocated or stored
549               as optimized all-zero clusters);
550
551           -   whether the data is known to read as zero (boolean field
552               "zero");
553
554           -   in order to make the output shorter, the target file is
555               expressed as a "depth"; for example, a depth of 2 refers to the
556               backing file of the backing file of filename.
557
558           In JSON format, the "offset" field is optional; it is absent in
559           cases where "human" format would omit the entry or exit with an
560           error.  If "data" is false and the "offset" field is present, the
561           corresponding sectors in the file are not yet in use, but they are
562           preallocated.
563
564           For more information, consult include/block/block.h in QEMU's
565           source code.
566
567       measure [--output=ofmt] [-O output_fmt] [-o options] [--size N |
568       [--object objectdef] [--image-opts] [-f fmt] [-l snapshot_param]
569       filename]
570           Calculate the file size required for a new image.  This information
571           can be used to size logical volumes or SAN LUNs appropriately for
572           the image that will be placed in them.  The values reported are
573           guaranteed to be large enough to fit the image.  The command can
574           output in the format ofmt which is either "human" or "json".  The
575           JSON output is an object of QAPI type "BlockMeasureInfo".
576
577           If the size N is given then act as if creating a new empty image
578           file using qemu-img create.  If filename is given then act as if
579           converting an existing image file using qemu-img convert.  The
580           format of the new file is given by output_fmt while the format of
581           an existing file is given by fmt.
582
583           A snapshot in an existing image can be specified using
584           snapshot_param.
585
586           The following fields are reported:
587
588                   required size: 524288
589                   fully allocated size: 1074069504
590
591           The "required size" is the file size of the new image.  It may be
592           smaller than the virtual disk size if the image format supports
593           compact representation.
594
595           The "fully allocated size" is the file size of the new image once
596           data has been written to all sectors.  This is the maximum size
597           that the image file can occupy with the exception of internal
598           snapshots, dirty bitmaps, vmstate data, and other advanced image
599           format features.
600
601       snapshot [--object objectdef] [--image-opts] [-U] [-q] [-l | -a
602       snapshot | -c snapshot | -d snapshot] filename
603           List, apply, create or delete snapshots in image filename.
604
605       rebase [--object objectdef] [--image-opts] [-U] [-q] [-f fmt] [-t
606       cache] [-T src_cache] [-p] [-u] -b backing_file [-F backing_fmt]
607       filename
608           Changes the backing file of an image. Only the formats "qcow2" and
609           "qed" support changing the backing file.
610
611           The backing file is changed to backing_file and (if the image
612           format of filename supports this) the backing file format is
613           changed to backing_fmt. If backing_file is specified as "" (the
614           empty string), then the image is rebased onto no backing file (i.e.
615           it will exist independently of any backing file).
616
617           If a relative path name is given, the backing file is looked up
618           relative to the directory containing filename.
619
620           cache specifies the cache mode to be used for filename, whereas
621           src_cache specifies the cache mode for reading backing files.
622
623           There are two different modes in which "rebase" can operate:
624
625           Safe mode
626               This is the default mode and performs a real rebase operation.
627               The new backing file may differ from the old one and qemu-img
628               rebase will take care of keeping the guest-visible content of
629               filename unchanged.
630
631               In order to achieve this, any clusters that differ between
632               backing_file and the old backing file of filename are merged
633               into filename before actually changing the backing file.
634
635               Note that the safe mode is an expensive operation, comparable
636               to converting an image. It only works if the old backing file
637               still exists.
638
639           Unsafe mode
640               qemu-img uses the unsafe mode if "-u" is specified. In this
641               mode, only the backing file name and format of filename is
642               changed without any checks on the file contents. The user must
643               take care of specifying the correct new backing file, or the
644               guest-visible content of the image will be corrupted.
645
646               This mode is useful for renaming or moving the backing file to
647               somewhere else.  It can be used without an accessible old
648               backing file, i.e. you can use it to fix an image whose backing
649               file has already been moved/renamed.
650
651           You can use "rebase" to perform a "diff" operation on two disk
652           images.  This can be useful when you have copied or cloned a guest,
653           and you want to get back to a thin image on top of a template or
654           base image.
655
656           Say that "base.img" has been cloned as "modified.img" by copying
657           it, and that the "modified.img" guest has run so there are now some
658           changes compared to "base.img".  To construct a thin image called
659           "diff.qcow2" that contains just the differences, do:
660
661                   qemu-img create -f qcow2 -b modified.img diff.qcow2
662                   qemu-img rebase -b base.img diff.qcow2
663
664           At this point, "modified.img" can be discarded, since "base.img +
665           diff.qcow2" contains the same information.
666
667       resize [--object objectdef] [--image-opts] [-f fmt]
668       [--preallocation=prealloc] [-q] [--shrink] filename [+ | -]size
669           Change the disk image as if it had been created with size.
670
671           Before using this command to shrink a disk image, you MUST use file
672           system and partitioning tools inside the VM to reduce allocated
673           file systems and partition sizes accordingly.  Failure to do so
674           will result in data loss!
675
676           When shrinking images, the "--shrink" option must be given. This
677           informs qemu-img that the user acknowledges all loss of data beyond
678           the truncated image's end.
679
680           After using this command to grow a disk image, you must use file
681           system and partitioning tools inside the VM to actually begin using
682           the new space on the device.
683
684           When growing an image, the "--preallocation" option may be used to
685           specify how the additional image area should be allocated on the
686           host.  See the format description in the "NOTES" section which
687           values are allowed.  Using this option may result in slightly more
688           data being allocated than necessary.
689

NOTES

691       Supported image file formats:
692
693       raw Raw disk image format (default). This format has the advantage of
694           being simple and easily exportable to all other emulators. If your
695           file system supports holes (for example in ext2 or ext3 on Linux or
696           NTFS on Windows), then only the written sectors will reserve space.
697           Use "qemu-img info" to know the real size used by the image or "ls
698           -ls" on Unix/Linux.
699
700           Supported options:
701
702           "preallocation"
703               Preallocation mode (allowed values: "off", "falloc", "full").
704               "falloc" mode preallocates space for image by calling
705               posix_fallocate().  "full" mode preallocates space for image by
706               writing data to underlying storage.  This data may or may not
707               be zero, depending on the storage location.
708
709       qcow2
710           QEMU image format, the most versatile format. Use it to have
711           smaller images (useful if your filesystem does not supports holes,
712           for example on Windows), optional AES encryption, zlib based
713           compression and support of multiple VM snapshots.
714
715           Supported options:
716
717           "compat"
718               Determines the qcow2 version to use. "compat=0.10" uses the
719               traditional image format that can be read by any QEMU since
720               0.10.  "compat=1.1" enables image format extensions that only
721               QEMU 1.1 and newer understand (this is the default). Amongst
722               others, this includes zero clusters, which allow efficient
723               copy-on-read for sparse images.
724
725           "backing_file"
726               File name of a base image (see create subcommand)
727
728           "backing_fmt"
729               Image format of the base image
730
731           "encryption"
732               If this option is set to "on", the image is encrypted with
733               128-bit AES-CBC.
734
735               The use of encryption in qcow and qcow2 images is considered to
736               be flawed by modern cryptography standards, suffering from a
737               number of design problems:
738
739               -   The AES-CBC cipher is used with predictable initialization
740                   vectors based on the sector number. This makes it
741                   vulnerable to chosen plaintext attacks which can reveal the
742                   existence of encrypted data.
743
744               -   The user passphrase is directly used as the encryption key.
745                   A poorly chosen or short passphrase will compromise the
746                   security of the encryption.
747
748               -   In the event of the passphrase being compromised there is
749                   no way to change the passphrase to protect data in any qcow
750                   images. The files must be cloned, using a different
751                   encryption passphrase in the new file. The original file
752                   must then be securely erased using a program like shred,
753                   though even this is ineffective with many modern storage
754                   technologies.
755
756               -   Initialization vectors used to encrypt sectors are based on
757                   the guest virtual sector number, instead of the host
758                   physical sector. When a disk image has multiple internal
759                   snapshots this means that data in multiple physical sectors
760                   is encrypted with the same initialization vector. With the
761                   CBC mode, this opens the possibility of watermarking
762                   attacks if the attack can collect multiple sectors
763                   encrypted with the same IV and some predictable data.
764                   Having multiple qcow2 images with the same passphrase also
765                   exposes this weakness since the passphrase is directly used
766                   as the key.
767
768               Use of qcow / qcow2 encryption is thus strongly discouraged.
769               Users are recommended to use an alternative encryption
770               technology such as the Linux dm-crypt / LUKS system.
771
772           "cluster_size"
773               Changes the qcow2 cluster size (must be between 512 and 2M).
774               Smaller cluster sizes can improve the image file size whereas
775               larger cluster sizes generally provide better performance.
776
777           "preallocation"
778               Preallocation mode (allowed values: "off", "metadata",
779               "falloc", "full"). An image with preallocated metadata is
780               initially larger but can improve performance when the image
781               needs to grow. "falloc" and "full" preallocations are like the
782               same options of "raw" format, but sets up metadata also.
783
784           "lazy_refcounts"
785               If this option is set to "on", reference count updates are
786               postponed with the goal of avoiding metadata I/O and improving
787               performance. This is particularly interesting with
788               cache=writethrough which doesn't batch metadata updates. The
789               tradeoff is that after a host crash, the reference count tables
790               must be rebuilt, i.e. on the next open an (automatic) "qemu-img
791               check -r all" is required, which may take some time.
792
793               This option can only be enabled if "compat=1.1" is specified.
794
795           "nocow"
796               If this option is set to "on", it will turn off COW of the
797               file. It's only valid on btrfs, no effect on other file
798               systems.
799
800               Btrfs has low performance when hosting a VM image file, even
801               more when the guest on the VM also using btrfs as file system.
802               Turning off COW is a way to mitigate this bad performance.
803               Generally there are two ways to turn off COW on btrfs: a)
804               Disable it by mounting with nodatacow, then all newly created
805               files will be NOCOW. b) For an empty file, add the NOCOW file
806               attribute. That's what this option does.
807
808               Note: this option is only valid to new or empty files. If there
809               is an existing file which is COW and has data blocks already,
810               it couldn't be changed to NOCOW by setting "nocow=on". One can
811               issue "lsattr filename" to check if the NOCOW flag is set or
812               not (Capital 'C' is NOCOW flag).
813
814       Other
815           QEMU also supports various other image file formats for
816           compatibility with older QEMU versions or other hypervisors,
817           including VMDK, VDI, VHD (vpc), VHDX, qcow1 and QED. For a full
818           list of supported formats see "qemu-img --help".  For a more
819           detailed description of these formats, see the QEMU Emulation User
820           Documentation.
821
822           The main purpose of the block drivers for these formats is image
823           conversion.  For running VMs, it is recommended to convert the disk
824           images to either raw or qcow2 in order to achieve good performance.
825

SEE ALSO

827       The HTML documentation of QEMU for more precise information and Linux
828       user mode emulator invocation.
829

AUTHOR

831       Fabrice Bellard
832
833
834
835                                  2020-03-17                     QEMU-IMG.1(1)
Impressum