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 ? for an overview of the options supported by
123       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 and vdi support consistency checks.
343
344              In case the image does not have any inconsistencies, check exits
345              with 0.  Other exit codes indicate  the  kind  of  inconsistency
346              found  or  if another error occurred. The following table summa‐
347              rizes all exit codes of the check subcommand:
348
349              0      Check completed, the image is (now) consistent
350
351              1      Check not completed because of internal errors
352
353              2      Check completed, image is corrupted
354
355              3      Check completed, image has leaked clusters,  but  is  not
356                     corrupted
357
358              63     Checks are not supported by the image format
359
360              If  -r is specified, exit codes representing the image state re‐
361              fer to the state after (the attempt at) repairing it. That is, a
362              successful  -r  all will yield the exit code 0, independently of
363              the image state before.
364
365       commit [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [-t CACHE] [-b
366       BASE] [-r RATE_LIMIT] [-d] [-p] FILENAME
367              Commit  the  changes  recorded  in FILENAME in its base image or
368              backing file.  If the backing file is smaller than the snapshot,
369              then the backing file will be resized to be the same size as the
370              snapshot.  If the snapshot is smaller than the backing file, the
371              backing  file  will  not  be truncated.  If you want the backing
372              file to match the size of the smaller snapshot, you  can  safely
373              truncate it yourself once the commit operation successfully com‐
374              pletes.
375
376              The image FILENAME is emptied after the operation has succeeded.
377              If  you  do  not need FILENAME afterwards and intend to drop it,
378              you may skip emptying FILENAME by specifying the -d flag.
379
380              If the backing chain of the given image file FILENAME  has  more
381              than  one layer, the backing file into which the changes will be
382              committed may be specified as BASE (which  has  to  be  part  of
383              FILENAME's backing chain). If BASE is not specified, the immedi‐
384              ate backing file of the top image (which is  FILENAME)  will  be
385              used. Note that after a commit operation all images between BASE
386              and the top image will be invalid and may  return  garbage  data
387              when read. For this reason, -b implies -d (so that the top image
388              stays valid).
389
390              The rate limit for the commit process is specified by -r.
391
392       compare [--object OBJECTDEF]  [--image-opts]  [-f  FMT]  [-F  FMT]  [-T
393       SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1 FILENAME2
394              Check  if  two images have the same content. You can compare im‐
395              ages with different format or settings.
396
397              The format is probed unless you specify it by -f (used for FILE‐
398              NAME1) and/or -F (used for FILENAME2) option.
399
400              By  default, images with different size are considered identical
401              if the larger image contains only unallocated and/or zeroed sec‐
402              tors  in the area after the end of the other image. In addition,
403              if any sector is not allocated in one image  and  contains  only
404              zero  bytes in the second one, it is evaluated as equal. You can
405              use Strict mode by specifying the -s option. When  compare  runs
406              in  Strict mode, it fails in case image size differs or a sector
407              is allocated in one image and is not  allocated  in  the  second
408              one.
409
410              By  default,  compare  prints out a result message. This message
411              displays information that both images are same or  the  position
412              of the first different byte. In addition, result message can re‐
413              port different image size in case Strict mode is used.
414
415              Compare exits with 0 in case the images are equal and with 1  in
416              case  the images differ. Other exit codes mean an error occurred
417              during execution and standard error output should contain an er‐
418              ror  message.   The  following table sumarizes all exit codes of
419              the compare subcommand:
420
421              0      Images are identical (or requested help was printed)
422
423              1      Images differ
424
425              2      Error on opening an image
426
427              3      Error on checking a sector allocation
428
429              4      Error on reading data
430
431       convert  [--object  OBJECTDEF]   [--image-opts]   [--target-image-opts]
432       [--target-is-zero]  [--bitmaps  [--skip-broken-bitmaps]] [-U] [-C] [-c]
433       [-p] [-q] [-n] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-O  OUTPUT_FMT]  [-B
434       BACKING_FILE  [-F  BACKING_FMT]]  [-o  OPTIONS] [-l SNAPSHOT_PARAM] [-S
435       SPARSE_SIZE] [-r RATE_LIMIT] [-m NUM_COROUTINES] [-W]  FILENAME  [FILE‐
436       NAME2 [...]] OUTPUT_FILENAME
437              Convert  the disk image FILENAME or a snapshot SNAPSHOT_PARAM to
438              disk image OUTPUT_FILENAME using format OUTPUT_FMT.  It  can  be
439              optionally compressed (-c option) or use any format specific op‐
440              tions like encryption (-o option).
441
442              Only the formats qcow and qcow2 support  compression.  The  com‐
443              pression  is  read-only. It means that if a compressed sector is
444              rewritten, then it is rewritten as uncompressed data.
445
446              Image conversion is also useful to get smaller image when  using
447              a  growable  format such as qcow: the empty sectors are detected
448              and suppressed from the destination image.
449
450              SPARSE_SIZE indicates the consecutive number of bytes  (defaults
451              to  4k)  that  must  contain only zeros for qemu-img to create a
452              sparse image during conversion. If SPARSE_SIZE is 0, the  source
453              will  not  be  scanned  for unallocated or zero sectors, and the
454              destination image will always be fully allocated.
455
456              You can use the BACKING_FILE option to force the output image to
457              be created as a copy on write image of the specified base image;
458              the BACKING_FILE should have the same  content  as  the  input's
459              base  image,  however  the path, image format (as given by BACK‐
460              ING_FMT), etc may differ.
461
462              If a relative path name is given, the backing file is looked  up
463              relative to the directory containing OUTPUT_FILENAME.
464
465              If  the  -n option is specified, the target volume creation will
466              be skipped. This is useful for formats such as rbd if the target
467              volume  has already been created with site specific options that
468              cannot be supplied through qemu-img.
469
470              Out of order writes can be enabled with -W  to  improve  perfor‐
471              mance.   This  is only recommended for preallocated devices like
472              host devices or other raw block devices. Out of order write does
473              not work in combination with creating compressed images.
474
475              NUM_COROUTINES  specifies  how  many coroutines work in parallel
476              during the convert process (defaults to 8).
477
478              Use of --bitmaps requests that any persistent bitmaps present in
479              the  original are also copied to the destination.  If any bitmap
480              is inconsistent in the source, the conversion will  fail  unless
481              --skip-broken-bitmaps is also specified to copy only the consis‐
482              tent bitmaps.
483
484       create [--object OBJECTDEF] [-q] [-f FMT] [-b  BACKING_FILE  [-F  BACK‐
485       ING_FMT]] [-u] [-o OPTIONS] FILENAME [SIZE]
486              Create  the new disk image FILENAME of size SIZE and format FMT.
487              Depending on the file format, you can add one  or  more  OPTIONS
488              that enable additional features of this format.
489
490              If  the  option  BACKING_FILE  is specified, then the image will
491              record only the differences from BACKING_FILE. No size needs  to
492              be  specified  in this case. BACKING_FILE will never be modified
493              unless you use the commit monitor command (or qemu-img commit).
494
495              If a relative path name is given, the backing file is looked  up
496              relative to the directory containing FILENAME.
497
498              Note  that  a given backing file will be opened to check that it
499              is valid. Use the -u option to enable unsafe backing file  mode,
500              which  means  that the image will be created even if the associ‐
501              ated backing file cannot be opened. A matching backing file must
502              be  created  or  additional  options be used to make the backing
503              file specification valid when you want to use an  image  created
504              this way.
505
506              The size can also be specified using the SIZE option with -o, it
507              doesn't need to be specified separately in this case.
508
509       dd  [--image-opts]  [-U]  [-f  FMT]  [-O  OUTPUT_FMT]   [bs=BLOCK_SIZE]
510       [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT
511              dd  copies from INPUT file to OUTPUT file converting it from FMT
512              format to OUTPUT_FMT format.
513
514              The data is by default read and  written  using  blocks  of  512
515              bytes   but   can  be  modified  by  specifying  BLOCK_SIZE.  If
516              count=BLOCKS is specified dd will stop reading input after read‐
517              ing BLOCKS input blocks.
518
519              The size syntax is similar to dd(1)'s size syntax.
520
521       info  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]  [--output=OFMT]
522       [--backing-chain] [-U] FILENAME
523              Give information about the disk image FILENAME. Use it  in  par‐
524              ticular to know the size reserved on disk which can be different
525              from the displayed size. If VM snapshots are stored in the  disk
526              image, they are displayed too.
527
528              If a disk image has a backing file chain, information about each
529              disk image in the chain can be recursively enumerated  by  using
530              the option --backing-chain.
531
532              For instance, if you have an image chain like:
533
534                 base.qcow2 <- snap1.qcow2 <- snap2.qcow2
535
536              To  enumerate  information  about  each  disk image in the above
537              chain, starting from top to base, do:
538
539                 qemu-img info --backing-chain snap2.qcow2
540
541              The command can output in the format OFMT which is either  human
542              or  json.   The JSON output is an object of QAPI type ImageInfo;
543              with --backing-chain, it is an array of ImageInfo objects.
544
545              --output=human reports the following information (for every  im‐
546              age in the chain):
547
548              image  The image file name
549
550              file format
551                     The image format
552
553              virtual size
554                     The size of the guest disk
555
556              disk size
557                     How  much  space the image file occupies on the host file
558                     system (may be shown as 0 if this information is unavail‐
559                     able, e.g. because there is no file system)
560
561              cluster_size
562                     Cluster size of the image format, if applicable
563
564              encrypted
565                     Whether the image is encrypted (only present if so)
566
567              cleanly shut down
568                     This  is  shown as no if the image is dirty and will have
569                     to be auto-repaired the next time it is opened in qemu.
570
571              backing file
572                     The backing file name, if present
573
574              backing file format
575                     The format of the backing file, if the image enforces it
576
577              Snapshot list
578                     A list of all internal snapshots
579
580              Format specific information
581                     Further information whose structure depends on the  image
582                     format.   This section is a textual representation of the
583                     respective ImageInfoSpecific* QAPI object (e.g.  ImageIn‐
584                     foSpecificQCow2 for qcow2 images).
585
586       map  [--object  OBJECTDEF] [--image-opts] [-f FMT] [--start-offset=OFF‐
587       SET] [--max-length=LEN] [--output=OFMT] [-U] FILENAME
588              Dump the metadata of image FILENAME and its backing file  chain.
589              In particular, this commands dumps the allocation state of every
590              sector of FILENAME, together with the topmost  file  that  allo‐
591              cates it in the backing file chain.
592
593              Two  option  formats  are  possible.  The default format (human)
594              only dumps known-nonzero areas of the file.  Known-zero parts of
595              the file are omitted altogether, and likewise for parts that are
596              not allocated throughout the chain.  qemu-img output will  iden‐
597              tify  a  file from where the data can be read, and the offset in
598              the file.  Each line will include four fields, the  first  three
599              of  which  are  hexadecimal numbers.  For example the first line
600              of:
601
602                 Offset          Length          Mapped to       File
603                 0               0x20000         0x50000         /tmp/overlay.qcow2
604                 0x100000        0x10000         0x95380000      /tmp/backing.qcow2
605
606              means that 0x20000 (131072) bytes starting at offset  0  in  the
607              image are available in /tmp/overlay.qcow2 (opened in raw format)
608              starting at offset 0x50000 (327680).  Data that  is  compressed,
609              encrypted,  or  otherwise not available in raw format will cause
610              an error if human format is in use.  Note that  file  names  can
611              include  newlines, thus it is not safe to parse this output for‐
612              mat in scripts.
613
614              The alternative format json will return an array of dictionaries
615              in  JSON  format.   It  will  include similar information in the
616              start, length, offset fields; it will also  include  other  more
617              specific information:
618
619              • boolean  field  data: true if the sectors contain actual data,
620                false if the sectors are either unallocated or stored as opti‐
621                mized all-zero clusters
622
623              • boolean field zero: true if the data is known to read as zero
624
625              • boolean field present: true if the data belongs to the backing
626                chain, false if rebasing the backing chain onto a deeper  file
627                would pick up data from the deeper file;
628
629              • integer  field  depth:  the  depth within the backing chain at
630                which the data was resolved; for example, a depth of 2  refers
631                to the backing file of the backing file of FILENAME.
632
633              In  JSON  format,  the offset field is optional; it is absent in
634              cases where human format would omit the entry or  exit  with  an
635              error.   If  data  is false and the offset field is present, the
636              corresponding sectors in the file are not yet in use,  but  they
637              are preallocated.
638
639              For  more  information,  consult include/block/block.h in QEMU's
640              source code.
641
642       measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--ob‐
643       ject OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]
644              Calculate the file size required for a new image.  This informa‐
645              tion can be used to size logical volumes or SAN  LUNs  appropri‐
646              ately for the image that will be placed in them.  The values re‐
647              ported are guaranteed to be large enough to fit the image.   The
648              command  can  output in the format OFMT which is either human or
649              json.  The JSON output is an object of QAPI  type  BlockMeasure‐
650              Info.
651
652              If the size N is given then act as if creating a new empty image
653              file using qemu-img create.  If FILENAME is given then act as if
654              converting  an  existing image file using qemu-img convert.  The
655              format of the new file is given by OUTPUT_FMT while  the  format
656              of an existing file is given by FMT.
657
658              A  snapshot  in  an  existing image can be specified using SNAP‐
659              SHOT_PARAM.
660
661              The following fields are reported:
662
663                 required size: 524288
664                 fully allocated size: 1074069504
665                 bitmaps size: 0
666
667              The required size is the file size of the new image.  It may  be
668              smaller  than the virtual disk size if the image format supports
669              compact representation.
670
671              The fully allocated size is the file size of the new image  once
672              data  has been written to all sectors.  This is the maximum size
673              that the image file can occupy with the  exception  of  internal
674              snapshots, dirty bitmaps, vmstate data, and other advanced image
675              format features.
676
677              The bitmaps size is the additional size  required  in  order  to
678              copy  bitmaps from a source image in addition to the guest-visi‐
679              ble data; the line is omitted if either  source  or  destination
680              lacks bitmap support, or 0 if bitmaps are supported but there is
681              nothing to copy.
682
683       snapshot [--object OBJECTDEF] [--image-opts] [-U] [-q] [-l |  -a  SNAP‐
684       SHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME
685              List, apply, create or delete snapshots in image FILENAME.
686
687       rebase  [--object  OBJECTDEF]  [--image-opts]  [-U]  [-q]  [-f FMT] [-t
688       CACHE] [-T SRC_CACHE] [-p] [-u] -b BACKING_FILE [-F BACKING_FMT]  FILE‐
689       NAME
690              Changes the backing file of an image. Only the formats qcow2 and
691              qed support changing the backing file.
692
693              The backing file is changed to BACKING_FILE and  (if  the  image
694              format  of  FILENAME  supports  this) the backing file format is
695              changed to BACKING_FMT. If BACKING_FILE is specified as ""  (the
696              empty  string),  then  the image is rebased onto no backing file
697              (i.e. it will exist independently of any backing file).
698
699              If a relative path name is given, the backing file is looked  up
700              relative to the directory containing FILENAME.
701
702              CACHE  specifies the cache mode to be used for FILENAME, whereas
703              SRC_CACHE specifies the cache mode for reading backing files.
704
705              There are two different modes in which rebase can operate:
706
707              Safe mode
708                     This is the default mode and performs a real rebase oper‐
709                     ation.  The  new backing file may differ from the old one
710                     and  qemu-img  rebase  will  take  care  of  keeping  the
711                     guest-visible content of FILENAME unchanged.
712
713                     In  order  to  achieve this, any clusters that differ be‐
714                     tween BACKING_FILE and the old backing file  of  FILENAME
715                     are  merged  into  FILENAME  before actually changing the
716                     backing file.
717
718                     Note that the safe mode is an expensive operation, compa‐
719                     rable  to  converting  an image. It only works if the old
720                     backing file still exists.
721
722              Unsafe mode
723                     qemu-img uses the unsafe mode if -u is specified. In this
724                     mode,  only  the backing file name and format of FILENAME
725                     is changed without any checks on the file  contents.  The
726                     user must take care of specifying the correct new backing
727                     file, or the guest-visible content of the image  will  be
728                     corrupted.
729
730                     This  mode  is  useful for renaming or moving the backing
731                     file to somewhere else.  It can be used without an acces‐
732                     sible old backing file, i.e. you can use it to fix an im‐
733                     age whose backing file has already been moved/renamed.
734
735              You can use rebase to perform a "diff" operation on two disk im‐
736              ages.   This  can  be  useful  when  you have copied or cloned a
737              guest, and you want to get back to a thin image on top of a tem‐
738              plate or base image.
739
740              Say that base.img has been cloned as modified.img by copying it,
741              and that the modified.img guest has run so there  are  now  some
742              changes  compared to base.img.  To construct a thin image called
743              diff.qcow2 that contains just the differences, do:
744
745                 qemu-img create -f qcow2 -b modified.img diff.qcow2
746                 qemu-img rebase -b base.img diff.qcow2
747
748              At this point, modified.img can be discarded, since  base.img  +
749              diff.qcow2 contains the same information.
750
751       resize  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]  [--prealloca‐
752       tion=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE
753              Change the disk image as if it had been created with SIZE.
754
755              Before using this command to shrink a disk image, you  MUST  use
756              file system and partitioning tools inside the VM to reduce allo‐
757              cated file systems and partition sizes accordingly.  Failure  to
758              do so will result in data loss!
759
760              When  shrinking  images, the --shrink option must be given. This
761              informs qemu-img that the user acknowledges all loss of data be‐
762              yond the truncated image's end.
763
764              After using this command to grow a disk image, you must use file
765              system and partitioning tools inside the VM  to  actually  begin
766              using the new space on the device.
767
768              When growing an image, the --preallocation option may be used to
769              specify how the additional image area should be allocated on the
770              host.   See  the  format  description in the Notes section which
771              values are allowed.  Using this option may  result  in  slightly
772              more data being allocated than necessary.
773

NOTES

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

AUTHOR

945       Fabrice Bellard
946
948       2023, The QEMU Project Developers
949
950
951
952
9537.0.0                            Jan 19, 2023                      QEMU-IMG(1)
Impressum