1QEMU-IMG(1)                          QEMU                          QEMU-IMG(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  vir‐
16       tual machine or any other process; this may destroy the image. Also, be
17       aware that querying an image that is being modified by another  process
18       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
35                 QEMU 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 con‐
43                 tain 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       [--force] -o OPTIONS FILENAME
56
57       bench  [-c COUNT] [-d DEPTH] [-f FMT] [--flush-interval=FLUSH_INTERVAL]
58       [-i AIO] [-n] [--no-drain] [-o  OFFSET]  [--pattern=PATTERN]  [-q]  [-s
59       BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE] [-w] [-U] FILENAME
60
61       bitmap (--merge SOURCE | --add | --remove | --clear | --enable | --dis‐
62       able)... [-b SOURCE_FILE [-F SOURCE_FMT]]  [-g  GRANULARITY]  [--object
63       OBJECTDEF] [--image-opts | -f FMT] FILENAME BITMAP
64
65       check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT]
66       [-r [leaks | all]] [-T SRC_CACHE] [-U] FILENAME
67
68       commit [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [-t CACHE] [-b
69       BASE] [-r RATE_LIMIT] [-d] [-p] FILENAME
70
71       compare  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]  [-F FMT] [-T
72       SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1 FILENAME2
73
74       convert  [--object  OBJECTDEF]   [--image-opts]   [--target-image-opts]
75       [--target-is-zero]  [--bitmaps]  [-U] [-C] [-c] [-p] [-q] [-n] [-f FMT]
76       [-t CACHE] [-T SRC_CACHE] [-O OUTPUT_FMT] [-B  BACKING_FILE  [-F  BACK‐
77       ING_FMT]]   [-o  OPTIONS]  [-l  SNAPSHOT_PARAM]  [-S  SPARSE_SIZE]  [-r
78       RATE_LIMIT] [-m NUM_COROUTINES] [-W]  [--salvage]  FILENAME  [FILENAME2
79       [...]] OUTPUT_FILENAME
80
81       create  [--object  OBJECTDEF]  [-q] [-f FMT] [-b BACKING_FILE [-F BACK‐
82       ING_FMT]] [-u] [-o OPTIONS] FILENAME [SIZE]
83
84       dd  [--image-opts]  [-U]  [-f  FMT]  [-O  OUTPUT_FMT]   [bs=BLOCK_SIZE]
85       [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT
86
87       info  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]  [--output=OFMT]
88       [--backing-chain] [-U] FILENAME
89
90       map [--object OBJECTDEF] [--image-opts] [-f  FMT]  [--start-offset=OFF‐
91       SET] [--max-length=LEN] [--output=OFMT] [-U] FILENAME
92
93       measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--ob‐
94       ject OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]
95
96       snapshot [--object OBJECTDEF] [--image-opts] [-U] [-q] [-l |  -a  SNAP‐
97       SHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME
98
99       rebase  [--object  OBJECTDEF]  [--image-opts]  [-U]  [-q]  [-f FMT] [-t
100       CACHE] [-T SRC_CACHE] [-p] [-u] -b BACKING_FILE [-F BACKING_FMT]  FILE‐
101       NAME
102
103       resize  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]  [--prealloca‐
104       tion=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE
105
106       Command parameters:
107
108       FILENAME is a disk image filename.
109
110       FMT is the disk image format.  It  is  guessed  automatically  in  most
111       cases. See below for a description of the supported disk formats.
112
113       SIZE  is  the disk image size in bytes. Optional suffixes k or K (kilo‐
114       byte, 1024) M (megabyte, 1024k) and G (gigabyte,  1024M)  and  T  (ter‐
115       abyte, 1024G) are supported.  b is ignored.
116
117       OUTPUT_FILENAME is the destination disk image filename.
118
119       OUTPUT_FMT is the destination format.
120
121       OPTIONS  is  a  comma  separated  list  of format specific options in a
122       name=value format. Use -o help for an overview of the options supported
123       by the used format or see the format descriptions below for details.
124
125       SNAPSHOT_PARAM  is  param  used for internal snapshot, format is 'snap‐
126       shot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'.
127
128       --object OBJECTDEF
129              is a QEMU user creatable object definition. See the qemu(1) man‐
130              ual  page  for  a description of the object properties. The most
131              common object type is a secret, which is used  to  supply  pass‐
132              words and/or encryption keys.
133
134       --image-opts
135              Indicates  that  the  source  FILENAME parameter is to be inter‐
136              preted as a full option string, not a plain filename.  This  pa‐
137              rameter is mutually exclusive with the -f parameter.
138
139       --target-image-opts
140              Indicates that the OUTPUT_FILENAME parameter(s) are to be inter‐
141              preted as a full option string, not a plain filename.  This  pa‐
142              rameter is mutually exclusive with the -O parameters. It is cur‐
143              rently required to also use the -n parameter to skip image  cre‐
144              ation. This restriction may be relaxed in a future release.
145
146       --force-share (-U)
147              If  specified,  qemu-img will open the image in shared mode, al‐
148              lowing other QEMU processes to open it in write mode. For  exam‐
149              ple,  this can be used to get the image information (with 'info'
150              subcommand) when the image is used by  a  running  guest.   Note
151              that  this could produce inconsistent results because of concur‐
152              rent metadata changes, etc. This option  is  only  allowed  when
153              opening images in read-only mode.
154
155       --backing-chain
156              Will  enumerate  information about backing files in a disk image
157              chain. Refer below for further description.
158
159       -c     Indicates that target image  must  be  compressed  (qcow  format
160              only).
161
162       -h     With  or  without  a command, shows help and lists the supported
163              formats.
164
165       -p     Display progress  bar  (compare,  convert  and  rebase  commands
166              only).  If the -p option is not used for a command that supports
167              it, the progress is reported when the process receives a SIGUSR1
168              or SIGINFO signal.
169
170       -q     Quiet mode - do not print any output (except errors). There's no
171              progress bar in case both -q and -p options are used.
172
173       -S SIZE
174              Indicates the consecutive number of bytes that must contain only
175              zeros  for  qemu-img to create a sparse image during conversion.
176              This value is rounded down to the nearest 512 bytes. You may use
177              the common size suffixes like k for kilobytes.
178
179       -t CACHE
180              Specifies  the cache mode that should be used with the (destina‐
181              tion) file. See  the  documentation  of  the  emulator's  -drive
182              cache=... option for allowed values.
183
184       -T SRC_CACHE
185              Specifies  the  cache  mode  that should be used with the source
186              file(s).  See  the  documentation  of  the   emulator's   -drive
187              cache=... option for allowed values.
188
189       Parameters to compare subcommand:
190
191       -f     First image format
192
193       -F     Second image format
194
195       -s     Strict mode - fail on different image size or sector allocation
196
197       Parameters to convert subcommand:
198
199       --bitmaps
200              Additionally  copy  all persistent bitmaps from the top layer of
201              the source
202
203       -n     Skip the creation of the target volume
204
205       -m     Number of parallel coroutines for the convert process
206
207       -W     Allow out-of-order writes to the destination.  This  option  im‐
208              proves performance, but is only recommended for preallocated de‐
209              vices like host devices or other raw block devices.
210
211       -C     Try to use copy offloading to move data  from  source  image  to
212              target. This may improve performance if the data is remote, such
213              as with NFS or iSCSI backends, but will not automatically  spar‐
214              sify  zero  sectors,  and may result in a fully allocated target
215              image depending on the host support for getting  allocation  in‐
216              formation.
217
218       -r     Rate limit for the convert process
219
220       --salvage
221              Try  to  ignore  I/O  errors when reading.  Unless in quiet mode
222              (-q), errors will still be printed.  Areas that cannot  be  read
223              from the source will be treated as containing only zeroes.
224
225       --target-is-zero
226              Assume that reading the destination image will always return ze‐
227              ros. This parameter is mutually exclusive with a destination im‐
228              age  that  has a backing file. It is required to also use the -n
229              parameter to skip image creation.
230
231       Parameters to dd subcommand:
232
233       bs=BLOCK_SIZE
234              Defines the block size
235
236       count=BLOCKS
237              Sets the number of input blocks to copy
238
239       if=INPUT
240              Sets the input file
241
242       of=OUTPUT
243              Sets the output file
244
245       skip=BLOCKS
246              Sets the number of input blocks to skip
247
248       Parameters to snapshot subcommand:
249
250       snapshot
251              Is the name of the snapshot to create, apply or delete
252
253       -a     Applies a snapshot (revert disk to saved state)
254
255       -c     Creates a snapshot
256
257       -d     Deletes a snapshot
258
259       -l     Lists all snapshots in the given image
260
261       Command description:
262
263       amend [--object OBJECTDEF] [--image-opts] [-p] [-q] [-f FMT] [-t CACHE]
264       [--force] -o OPTIONS FILENAME
265              Amends  the  image  format  specific  OPTIONS for the image file
266              FILENAME. Not all file formats support this operation.
267
268              The set of options that can be amended are dependent on the  im‐
269              age  format,  but note that amending the backing chain relation‐
270              ship should instead be performed with qemu-img rebase.
271
272              --force allows some unsafe operations. Currently for -f luks, it
273              allows to erase the last encryption key, and to overwrite an ac‐
274              tive encryption key.
275
276       bench [-c COUNT] [-d DEPTH] [-f FMT]  [--flush-interval=FLUSH_INTERVAL]
277       [-i  AIO]  [-n]  [--no-drain]  [-o OFFSET] [--pattern=PATTERN] [-q] [-s
278       BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE] [-w] [-U] FILENAME
279              Run a simple sequential I/O benchmark on the specified image. If
280              -w  is  specified,  a  write test is performed, otherwise a read
281              test is performed.
282
283              A total number of COUNT I/O requests  is  performed,  each  BUF‐
284              FER_SIZE bytes in size, and with DEPTH requests in parallel. The
285              first request starts at the position given by OFFSET, each  fol‐
286              lowing  request  increases the current position by STEP_SIZE. If
287              STEP_SIZE is not given, BUFFER_SIZE is used for its value.
288
289              If FLUSH_INTERVAL is specified for a  write  test,  the  request
290              queue  is  drained  and  a flush is issued before new writes are
291              made whenever the number of remaining requests is a multiple  of
292              FLUSH_INTERVAL. If additionally --no-drain is specified, a flush
293              is issued without draining the request queue first.
294
295              if -i is specified, AIO option can be used to specify  different
296              AIO backends: threads, native or io_uring.
297
298              If  -n is specified, the native AIO backend is used if possible.
299              On Linux, this option only works if -t none or -t directsync  is
300              specified as well.
301
302              For  write tests, by default a buffer filled with zeros is writ‐
303              ten. This can be overridden with a  pattern  byte  specified  by
304              PATTERN.
305
306       bitmap (--merge SOURCE | --add | --remove | --clear | --enable | --dis‐
307       able)... [-b SOURCE_FILE [-F SOURCE_FMT]]  [-g  GRANULARITY]  [--object
308       OBJECTDEF] [--image-opts | -f FMT] FILENAME BITMAP
309              Perform  one or more modifications of the persistent bitmap BIT‐
310              MAP in the disk image FILENAME.  The various modifications are:
311
312              --add to create BITMAP, enabled to record future edits.
313
314              --remove to remove BITMAP.
315
316              --clear to clear BITMAP.
317
318              --enable to change BITMAP to start recording future edits.
319
320              --disable to change BITMAP to stop recording future edits.
321
322              --merge to merge the contents of the SOURCE bitmap into BITMAP.
323
324              Additional options include -g which sets a non-default GRANULAR‐
325              ITY  for --add, and -b and -F which select an alternative source
326              file for all SOURCE bitmaps used by --merge.
327
328              To see what bitmaps are present in an image, use qemu-img info.
329
330       check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT]
331       [-r [leaks | all]] [-T SRC_CACHE] [-U] FILENAME
332              Perform a consistency check on the disk image FILENAME. The com‐
333              mand can output in the format OFMT  which  is  either  human  or
334              json.  The JSON output is an object of QAPI type ImageCheck.
335
336              If -r is specified, qemu-img tries to repair any inconsistencies
337              found during the check. -r leaks  repairs  only  cluster  leaks,
338              whereas  -r all fixes all kinds of errors, with a higher risk of
339              choosing the wrong fix or hiding corruption that has already oc‐
340              curred.
341
342              Only  the formats qcow2, qed, parallels, vhdx, vmdk and vdi sup‐
343              port consistency checks.
344
345              In case the image does not have any inconsistencies, check exits
346              with  0.   Other  exit  codes indicate the kind of inconsistency
347              found or if another error occurred. The following  table  summa‐
348              rizes all exit codes of the check subcommand:
349
350              0      Check completed, the image is (now) consistent
351
352              1      Check not completed because of internal errors
353
354              2      Check completed, image is corrupted
355
356              3      Check  completed,  image  has leaked clusters, but is not
357                     corrupted
358
359              63     Checks are not supported by the image format
360
361              If -r is specified, exit codes representing the image state  re‐
362              fer to the state after (the attempt at) repairing it. That is, a
363              successful -r all will yield the exit code 0,  independently  of
364              the image state before.
365
366       commit [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [-t CACHE] [-b
367       BASE] [-r RATE_LIMIT] [-d] [-p] FILENAME
368              Commit the changes recorded in FILENAME in  its  base  image  or
369              backing file.  If the backing file is smaller than the snapshot,
370              then the backing file will be resized to be the same size as the
371              snapshot.  If the snapshot is smaller than the backing file, the
372              backing file will not be truncated.  If  you  want  the  backing
373              file  to  match the size of the smaller snapshot, you can safely
374              truncate it yourself once the commit operation successfully com‐
375              pletes.
376
377              The image FILENAME is emptied after the operation has succeeded.
378              If you do not need FILENAME afterwards and intend  to  drop  it,
379              you may skip emptying FILENAME by specifying the -d flag.
380
381              If  the  backing chain of the given image file FILENAME has more
382              than one layer, the backing file into which the changes will  be
383              committed  may  be  specified  as  BASE (which has to be part of
384              FILENAME's backing chain). If BASE is not specified, the immedi‐
385              ate  backing  file  of the top image (which is FILENAME) will be
386              used. Note that after a commit operation all images between BASE
387              and  the  top  image will be invalid and may return garbage data
388              when read. For this reason, -b implies -d (so that the top image
389              stays valid).
390
391              The rate limit for the commit process is specified by -r.
392
393       compare  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]  [-F FMT] [-T
394       SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1 FILENAME2
395              Check if two images have the same content. You can  compare  im‐
396              ages with different format or settings.
397
398              The format is probed unless you specify it by -f (used for FILE‐
399              NAME1) and/or -F (used for FILENAME2) option.
400
401              By default, images with different size are considered  identical
402              if the larger image contains only unallocated and/or zeroed sec‐
403              tors in the area after the end of the other image. In  addition,
404              if  any  sector  is not allocated in one image and contains only
405              zero bytes in the second one, it is evaluated as equal. You  can
406              use  Strict  mode by specifying the -s option. When compare runs
407              in Strict mode, it fails in case image size differs or a  sector
408              is  allocated  in  one  image and is not allocated in the second
409              one.
410
411              By default, compare prints out a result  message.  This  message
412              displays  information  that both images are same or the position
413              of the first different byte. In addition, result message can re‐
414              port different image size in case Strict mode is used.
415
416              Compare  exits with 0 in case the images are equal and with 1 in
417              case the images differ. Other exit codes mean an error  occurred
418              during execution and standard error output should contain an er‐
419              ror message.  The following table sumarizes all  exit  codes  of
420              the compare subcommand:
421
422              0      Images are identical (or requested help was printed)
423
424              1      Images differ
425
426              2      Error on opening an image
427
428              3      Error on checking a sector allocation
429
430              4      Error on reading data
431
432       convert   [--object   OBJECTDEF]  [--image-opts]  [--target-image-opts]
433       [--target-is-zero] [--bitmaps [--skip-broken-bitmaps]] [-U]  [-C]  [-c]
434       [-p]  [-q]  [-n] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-O OUTPUT_FMT] [-B
435       BACKING_FILE [-F BACKING_FMT]] [-o  OPTIONS]  [-l  SNAPSHOT_PARAM]  [-S
436       SPARSE_SIZE]  [-r  RATE_LIMIT] [-m NUM_COROUTINES] [-W] FILENAME [FILE‐
437       NAME2 [...]] OUTPUT_FILENAME
438              Convert the disk image FILENAME or a snapshot SNAPSHOT_PARAM  to
439              disk  image  OUTPUT_FILENAME  using format OUTPUT_FMT. It can be
440              optionally compressed (-c option) or use any format specific op‐
441              tions like encryption (-o option).
442
443              Only  the  formats  qcow and qcow2 support compression. The com‐
444              pression is read-only. It means that if a compressed  sector  is
445              rewritten, then it is rewritten as uncompressed data.
446
447              Image  conversion is also useful to get smaller image when using
448              a growable format such as qcow: the empty sectors  are  detected
449              and suppressed from the destination image.
450
451              SPARSE_SIZE  indicates the consecutive number of bytes (defaults
452              to 4k) that must contain only zeros for  qemu-img  to  create  a
453              sparse  image during conversion. If SPARSE_SIZE is 0, the source
454              will not be scanned for unallocated or  zero  sectors,  and  the
455              destination image will always be fully allocated.
456
457              You can use the BACKING_FILE option to force the output image to
458              be created as a copy on write image of the specified base image;
459              the  BACKING_FILE  should  have  the same content as the input's
460              base image, however the path, image format (as  given  by  BACK‐
461              ING_FMT), etc may differ.
462
463              If  a relative path name is given, the backing file is looked up
464              relative to the directory containing OUTPUT_FILENAME.
465
466              If the -n option is specified, the target volume  creation  will
467              be skipped. This is useful for formats such as rbd if the target
468              volume has already been created with site specific options  that
469              cannot be supplied through qemu-img.
470
471              Out  of  order  writes can be enabled with -W to improve perfor‐
472              mance.  This is only recommended for preallocated  devices  like
473              host devices or other raw block devices. Out of order write does
474              not work in combination with creating compressed images.
475
476              NUM_COROUTINES specifies how many coroutines  work  in  parallel
477              during the convert process (defaults to 8).
478
479              Use of --bitmaps requests that any persistent bitmaps present in
480              the original are also copied to the destination.  If any  bitmap
481              is  inconsistent  in the source, the conversion will fail unless
482              --skip-broken-bitmaps is also specified to copy only the consis‐
483              tent bitmaps.
484
485       create  [--object  OBJECTDEF]  [-q] [-f FMT] [-b BACKING_FILE [-F BACK‐
486       ING_FMT]] [-u] [-o OPTIONS] FILENAME [SIZE]
487              Create the new disk image FILENAME of size SIZE and format  FMT.
488              Depending  on  the  file format, you can add one or more OPTIONS
489              that enable additional features of this format.
490
491              If the option BACKING_FILE is specified,  then  the  image  will
492              record  only the differences from BACKING_FILE. No size needs to
493              be specified in this case. BACKING_FILE will never  be  modified
494              unless you use the commit monitor command (or qemu-img commit).
495
496              If  a relative path name is given, the backing file is looked up
497              relative to the directory containing FILENAME.
498
499              Note that a given backing file will be opened to check  that  it
500              is  valid. Use the -u option to enable unsafe backing file mode,
501              which means that the image will be created even if  the  associ‐
502              ated backing file cannot be opened. A matching backing file must
503              be created or additional options be used  to  make  the  backing
504              file  specification  valid when you want to use an image created
505              this way.
506
507              The size can also be specified using the SIZE option with -o, it
508              doesn't need to be specified separately in this case.
509
510       dd   [--image-opts]  [-U]  [-f  FMT]  [-O  OUTPUT_FMT]  [bs=BLOCK_SIZE]
511       [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT
512              dd copies from INPUT file to OUTPUT file converting it from  FMT
513              format to OUTPUT_FMT format.
514
515              The  data  is  by  default  read and written using blocks of 512
516              bytes  but  can  be  modified  by  specifying   BLOCK_SIZE.   If
517              count=BLOCKS is specified dd will stop reading input after read‐
518              ing BLOCKS input blocks.
519
520              The size syntax is similar to dd(1)'s size syntax.
521
522       info  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]  [--output=OFMT]
523       [--backing-chain] [-U] FILENAME
524              Give  information  about the disk image FILENAME. Use it in par‐
525              ticular to know the size reserved on disk which can be different
526              from  the displayed size. If VM snapshots are stored in the disk
527              image, they are displayed too.
528
529              If a disk image has a backing file chain, information about each
530              disk  image  in the chain can be recursively enumerated by using
531              the option --backing-chain.
532
533              For instance, if you have an image chain like:
534
535                 base.qcow2 <- snap1.qcow2 <- snap2.qcow2
536
537              To enumerate information about each  disk  image  in  the  above
538              chain, starting from top to base, do:
539
540                 qemu-img info --backing-chain snap2.qcow2
541
542              The  command can output in the format OFMT which is either human
543              or json.  The JSON output is an object of QAPI  type  ImageInfo;
544              with --backing-chain, it is an array of ImageInfo objects.
545
546              --output=human  reports the following information (for every im‐
547              age in the chain):
548
549              image  The image file name
550
551              file format
552                     The image format
553
554              virtual size
555                     The size of the guest disk
556
557              disk size
558                     How much space the image file occupies on the  host  file
559                     system (may be shown as 0 if this information is unavail‐
560                     able, e.g. because there is no file system)
561
562              cluster_size
563                     Cluster size of the image format, if applicable
564
565              encrypted
566                     Whether the image is encrypted (only present if so)
567
568              cleanly shut down
569                     This is shown as no if the image is dirty and  will  have
570                     to be auto-repaired the next time it is opened in qemu.
571
572              backing file
573                     The backing file name, if present
574
575              backing file format
576                     The format of the backing file, if the image enforces it
577
578              Snapshot list
579                     A list of all internal snapshots
580
581              Format specific information
582                     Further  information whose structure depends on the image
583                     format.  This section is a textual representation of  the
584                     respective  ImageInfoSpecific* QAPI object (e.g. ImageIn‐
585                     foSpecificQCow2 for qcow2 images).
586
587       map [--object OBJECTDEF] [--image-opts] [-f  FMT]  [--start-offset=OFF‐
588       SET] [--max-length=LEN] [--output=OFMT] [-U] FILENAME
589              Dump  the metadata of image FILENAME and its backing file chain.
590              In particular, this commands dumps the allocation state of every
591              sector  of  FILENAME,  together with the topmost file that allo‐
592              cates it in the backing file chain.
593
594              Two option formats are possible.   The  default  format  (human)
595              only dumps known-nonzero areas of the file.  Known-zero parts of
596              the file are omitted altogether, and likewise for parts that are
597              not  allocated throughout the chain.  qemu-img output will iden‐
598              tify a file from where the data can be read, and the  offset  in
599              the  file.   Each line will include four fields, the first three
600              of which are hexadecimal numbers.  For example  the  first  line
601              of:
602
603                 Offset          Length          Mapped to       File
604                 0               0x20000         0x50000         /tmp/overlay.qcow2
605                 0x100000        0x10000         0x95380000      /tmp/backing.qcow2
606
607              means  that  0x20000  (131072) bytes starting at offset 0 in the
608              image are available in /tmp/overlay.qcow2 (opened in raw format)
609              starting  at  offset 0x50000 (327680).  Data that is compressed,
610              encrypted, or otherwise not available in raw format  will  cause
611              an  error  if  human format is in use.  Note that file names can
612              include newlines, thus it is not safe to parse this output  for‐
613              mat in scripts.
614
615              The alternative format json will return an array of dictionaries
616              in JSON format.  It will  include  similar  information  in  the
617              start,  length,  offset  fields; it will also include other more
618              specific information:
619
620              • boolean field data: true if the sectors contain  actual  data,
621                false if the sectors are either unallocated or stored as opti‐
622                mized all-zero clusters
623
624              • boolean field zero: true if the data is known to read as zero
625
626              • boolean field present: true if the data belongs to the backing
627                chain,  false if rebasing the backing chain onto a deeper file
628                would pick up data from the deeper file;
629
630              • integer field depth: the depth within  the  backing  chain  at
631                which  the data was resolved; for example, a depth of 2 refers
632                to the backing file of the backing file of FILENAME.
633
634              In JSON format, the offset field is optional; it  is  absent  in
635              cases  where  human  format would omit the entry or exit with an
636              error.  If data is false and the offset field  is  present,  the
637              corresponding  sectors  in the file are not yet in use, but they
638              are preallocated.
639
640              For more information, consult  include/block/block.h  in  QEMU's
641              source code.
642
643       measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--ob‐
644       ject OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]
645              Calculate the file size required for a new image.  This informa‐
646              tion  can  be used to size logical volumes or SAN LUNs appropri‐
647              ately for the image that will be placed in them.  The values re‐
648              ported  are guaranteed to be large enough to fit the image.  The
649              command can output in the format OFMT which is either  human  or
650              json.   The  JSON output is an object of QAPI type BlockMeasure‐
651              Info.
652
653              If the size N is given then act as if creating a new empty image
654              file using qemu-img create.  If FILENAME is given then act as if
655              converting an existing image file using qemu-img  convert.   The
656              format  of  the new file is given by OUTPUT_FMT while the format
657              of an existing file is given by FMT.
658
659              A snapshot in an existing image can  be  specified  using  SNAP‐
660              SHOT_PARAM.
661
662              The following fields are reported:
663
664                 required size: 524288
665                 fully allocated size: 1074069504
666                 bitmaps size: 0
667
668              The  required size is the file size of the new image.  It may be
669              smaller than the virtual disk size if the image format  supports
670              compact representation.
671
672              The  fully allocated size is the file size of the new image once
673              data has been written to all sectors.  This is the maximum  size
674              that  the  image  file can occupy with the exception of internal
675              snapshots, dirty bitmaps, vmstate data, and other advanced image
676              format features.
677
678              The  bitmaps  size  is  the additional size required in order to
679              copy bitmaps from a source image in addition to the  guest-visi‐
680              ble  data;  the  line is omitted if either source or destination
681              lacks bitmap support, or 0 if bitmaps are supported but there is
682              nothing to copy.
683
684       snapshot  [--object  OBJECTDEF] [--image-opts] [-U] [-q] [-l | -a SNAP‐
685       SHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME
686              List, apply, create or delete snapshots in image FILENAME.
687
688       rebase [--object OBJECTDEF]  [--image-opts]  [-U]  [-q]  [-f  FMT]  [-t
689       CACHE]  [-T SRC_CACHE] [-p] [-u] -b BACKING_FILE [-F BACKING_FMT] FILE‐
690       NAME
691              Changes the backing file of an image. Only the formats qcow2 and
692              qed support changing the backing file.
693
694              The  backing  file  is changed to BACKING_FILE and (if the image
695              format of FILENAME supports this) the  backing  file  format  is
696              changed  to BACKING_FMT. If BACKING_FILE is specified as "" (the
697              empty string), then the image is rebased onto  no  backing  file
698              (i.e. it will exist independently of any backing file).
699
700              If  a relative path name is given, the backing file is looked up
701              relative to the directory containing FILENAME.
702
703              CACHE specifies the cache mode to be used for FILENAME,  whereas
704              SRC_CACHE specifies the cache mode for reading backing files.
705
706              There are two different modes in which rebase can operate:
707
708              Safe mode
709                     This is the default mode and performs a real rebase oper‐
710                     ation. The new backing file may differ from the  old  one
711                     and  qemu-img  rebase  will  take  care  of  keeping  the
712                     guest-visible content of FILENAME unchanged.
713
714                     In order to achieve this, any clusters  that  differ  be‐
715                     tween  BACKING_FILE  and the old backing file of FILENAME
716                     are merged into FILENAME  before  actually  changing  the
717                     backing file.
718
719                     Note that the safe mode is an expensive operation, compa‐
720                     rable to converting an image. It only works  if  the  old
721                     backing file still exists.
722
723              Unsafe mode
724                     qemu-img uses the unsafe mode if -u is specified. In this
725                     mode, only the backing file name and format  of  FILENAME
726                     is  changed  without any checks on the file contents. The
727                     user must take care of specifying the correct new backing
728                     file,  or  the guest-visible content of the image will be
729                     corrupted.
730
731                     This mode is useful for renaming or  moving  the  backing
732                     file to somewhere else.  It can be used without an acces‐
733                     sible old backing file, i.e. you can use it to fix an im‐
734                     age whose backing file has already been moved/renamed.
735
736              You can use rebase to perform a "diff" operation on two disk im‐
737              ages.  This can be useful when  you  have  copied  or  cloned  a
738              guest, and you want to get back to a thin image on top of a tem‐
739              plate or base image.
740
741              Say that base.img has been cloned as modified.img by copying it,
742              and  that  the  modified.img guest has run so there are now some
743              changes compared to base.img.  To construct a thin image  called
744              diff.qcow2 that contains just the differences, do:
745
746                 qemu-img create -f qcow2 -b modified.img diff.qcow2
747                 qemu-img rebase -b base.img diff.qcow2
748
749              At  this  point, modified.img can be discarded, since base.img +
750              diff.qcow2 contains the same information.
751
752       resize  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]  [--prealloca‐
753       tion=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE
754              Change the disk image as if it had been created with SIZE.
755
756              Before  using  this command to shrink a disk image, you MUST use
757              file system and partitioning tools inside the VM to reduce allo‐
758              cated  file systems and partition sizes accordingly.  Failure to
759              do so will result in data loss!
760
761              When shrinking images, the --shrink option must be  given.  This
762              informs qemu-img that the user acknowledges all loss of data be‐
763              yond the truncated image's end.
764
765              After using this command to grow a disk image, you must use file
766              system  and  partitioning  tools inside the VM to actually begin
767              using the new space on the device.
768
769              When growing an image, the --preallocation option may be used to
770              specify how the additional image area should be allocated on the
771              host.  See the format description in  the  Notes  section  which
772              values  are  allowed.   Using this option may result in slightly
773              more data being allocated than necessary.
774

NOTES

776       Supported image file formats:
777
778       raw
779          Raw disk image format (default). This format has  the  advantage  of
780          being  simple  and easily exportable to all other emulators. If your
781          file system supports holes (for example in ext2 or ext3 on Linux  or
782          NTFS  on Windows), then only the written sectors will reserve space.
783          Use qemu-img info to know the real size used by the image or ls  -ls
784          on Unix/Linux.
785
786          Supported options:
787
788          preallocation
789                 Preallocation mode (allowed values: off, falloc, full).  fal‐
790                 loc mode preallocates space for image by calling posix_fallo‐
791                 cate().   full  mode  preallocates space for image by writing
792                 data to underlying storage.  This data  may  or  may  not  be
793                 zero, depending on the storage location.
794
795       qcow2
796          QEMU image format, the most versatile format. Use it to have smaller
797          images (useful if your filesystem does not supports holes, for exam‐
798          ple on Windows), optional AES encryption, zlib based compression and
799          support of multiple VM snapshots.
800
801          Supported options:
802
803          compat Determines the qcow2 version to  use.  compat=0.10  uses  the
804                 traditional  image  format that can be read by any QEMU since
805                 0.10.  compat=1.1 enables image format extensions  that  only
806                 QEMU  1.1 and newer understand (this is the default). Amongst
807                 others, this includes zero clusters,  which  allow  efficient
808                 copy-on-read for sparse images.
809
810          backing_file
811                 File name of a base image (see create subcommand)
812
813          backing_fmt
814                 Image format of the base image
815
816          encryption
817                 If  this  option  is  set  to on, the image is encrypted with
818                 128-bit AES-CBC.
819
820                 The use of encryption in qcow and qcow2 images is  considered
821                 to be flawed by modern cryptography standards, suffering from
822                 a number of design problems:
823
824                 • The AES-CBC cipher is used with predictable  initialization
825                   vectors  based on the sector number. This makes it vulnera‐
826                   ble to chosen plaintext attacks which can reveal the  exis‐
827                   tence of encrypted data.
828
829                 • The user passphrase is directly used as the encryption key.
830                   A poorly chosen or short passphrase will compromise the se‐
831                   curity of the encryption.
832
833                 • In  the  event of the passphrase being compromised there is
834                   no way to change the passphrase to protect data in any qcow
835                   images. The files must be cloned, using a different encryp‐
836                   tion passphrase in the new file.  The  original  file  must
837                   then  be securely erased using a program like shred, though
838                   even this is ineffective with many modern storage technolo‐
839                   gies.
840
841                 • Initialization vectors used to encrypt sectors are based on
842                   the guest virtual sector number, instead of the host physi‐
843                   cal  sector.  When a disk image has multiple internal snap‐
844                   shots this means that data in multiple physical sectors  is
845                   encrypted with the same initialization vector. With the CBC
846                   mode, this opens the possibility of watermarking attacks if
847                   the  attack can collect multiple sectors encrypted with the
848                   same IV and some predictable data.  Having  multiple  qcow2
849                   images  with the same passphrase also exposes this weakness
850                   since the passphrase is directly used as the key.
851
852                 Use of qcow / qcow2 encryption is thus strongly  discouraged.
853                 Users  are recommended to use an alternative encryption tech‐
854                 nology such as the Linux dm-crypt / LUKS system.
855
856          cluster_size
857                 Changes the qcow2 cluster size (must be between 512 and  2M).
858                 Smaller cluster sizes can improve the image file size whereas
859                 larger cluster sizes generally provide better performance.
860
861          preallocation
862                 Preallocation mode (allowed values:  off,  metadata,  falloc,
863                 full).  An  image  with  preallocated  metadata  is initially
864                 larger but can improve performance when the  image  needs  to
865                 grow.  falloc  and  full preallocations are like the same op‐
866                 tions of raw format, but sets up metadata also.
867
868          lazy_refcounts
869                 If this option is set to  on,  reference  count  updates  are
870                 postponed  with the goal of avoiding metadata I/O and improv‐
871                 ing  performance.  This  is  particularly  interesting   with
872                 cache=writethrough  which doesn't batch metadata updates. The
873                 tradeoff is that after a host crash, the reference count  ta‐
874                 bles  must  be  rebuilt, i.e. on the next open an (automatic)
875                 qemu-img check -r all is required, which may take some time.
876
877                 This option can only be enabled if compat=1.1 is specified.
878
879          nocow  If this option is set to on, it will  turn  off  COW  of  the
880                 file.  It's only valid on btrfs, no effect on other file sys‐
881                 tems.
882
883                 Btrfs has low performance when hosting a VM image file,  even
884                 more  when  the guest on the VM also using btrfs as file sys‐
885                 tem. Turning off COW is a way to mitigate  this  bad  perfor‐
886                 mance. Generally there are two ways to turn off COW on btrfs:
887
888                 • Disable  it by mounting with nodatacow, then all newly cre‐
889                   ated files will be NOCOW
890
891                 • For an empty file, add the  NOCOW  file  attribute.  That's
892                   what this option does.
893
894                 Note:  this  option  is  only valid to new or empty files. If
895                 there is an existing file which is COW and  has  data  blocks
896                 already, it couldn't be changed to NOCOW by setting nocow=on.
897                 One can issue lsattr filename to check if the NOCOW  flag  is
898                 set or not (Capital 'C' is NOCOW flag).
899
900          data_file
901                 Filename  where all guest data will be stored. If this option
902                 is used, the qcow2 file will only contain the  image's  meta‐
903                 data.
904
905                 Note:  Data loss will occur if the given filename already ex‐
906                 ists when  using  this  option  with  qemu-img  create  since
907                 qemu-img  will  create  the  data  file anew, overwriting the
908                 file's original contents. To simply update the  reference  to
909                 point to the given pre-existing file, use qemu-img amend.
910
911          data_file_raw
912                 If this option is set to on, QEMU will always keep the exter‐
913                 nal data file consistent as a standalone read-only raw image.
914
915                 It does this by forwarding all write accesses  to  the  qcow2
916                 file  through  to the raw data file, including their offsets.
917                 Therefore, data that is visible on the qcow2 node  (i.e.,  to
918                 the  guest)  at  some offset is visible at the same offset in
919                 the raw data file. This results in  a  read-only  raw  image.
920                 Writes  that  bypass the qcow2 metadata may corrupt the qcow2
921                 metadata because the out-of-band writes  may  result  in  the
922                 metadata falling out of sync with the raw image.
923
924                 If  this  option is off, QEMU will use the data file to store
925                 data in an arbitrary manner. The file’s content will not make
926                 sense  without the accompanying qcow2 metadata. Where data is
927                 written will have no relation to its offset as  seen  by  the
928                 guest,  and some writes (specifically zero writes) may not be
929                 forwarded to the data file at all, but will only  be  handled
930                 by modifying qcow2 metadata.
931
932                 This option can only be enabled if data_file is set.
933
934       Other
935          QEMU  also supports various other image file formats for compatibil‐
936          ity with older QEMU versions or other hypervisors,  including  VMDK,
937          VDI,  VHD  (vpc),  VHDX, qcow1 and QED. For a full list of supported
938          formats see qemu-img --help.  For a  more  detailed  description  of
939          these formats, see the QEMU block drivers reference documentation.
940
941          The  main  purpose  of  the block drivers for these formats is image
942          conversion.  For running VMs, it is recommended to convert the  disk
943          images to either raw or qcow2 in order to achieve good performance.
944

AUTHOR

946       Fabrice Bellard
947
949       2023, The QEMU Project Developers
950
951
952
953
9547.2.6                            Sep 26, 2023                      QEMU-IMG(1)
Impressum