]>
Commit | Line | Data |
---|---|---|
8a1f7d29 | 1 | ======================= |
e13c59fa PM |
2 | QEMU disk image utility |
3 | ======================= | |
4 | ||
5 | Synopsis | |
6 | -------- | |
7 | ||
8 | **qemu-img** [*standard options*] *command* [*command options*] | |
9 | ||
10 | Description | |
11 | ----------- | |
12 | ||
13 | qemu-img allows you to create, convert and modify images offline. It can handle | |
14 | all image formats supported by QEMU. | |
15 | ||
16 | **Warning:** Never use qemu-img to modify images in use by a running virtual | |
17 | machine or any other process; this may destroy the image. Also, be aware that | |
18 | querying an image that is being modified by another process may encounter | |
19 | inconsistent state. | |
20 | ||
21 | Options | |
22 | ------- | |
23 | ||
24 | .. program:: qemu-img | |
25 | ||
26 | Standard options: | |
27 | ||
28 | .. option:: -h, --help | |
29 | ||
30 | Display this help and exit | |
31 | ||
32 | .. option:: -V, --version | |
33 | ||
34 | Display version information and exit | |
35 | ||
36 | .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] | |
37 | ||
bb43ee6c | 38 | .. include:: ../qemu-option-trace.rst.inc |
e13c59fa PM |
39 | |
40 | The following commands are supported: | |
41 | ||
42 | .. hxtool-doc:: qemu-img-cmds.hx | |
43 | ||
44 | Command parameters: | |
45 | ||
46 | *FILENAME* is a disk image filename. | |
47 | ||
48 | *FMT* is the disk image format. It is guessed automatically in most | |
49 | cases. See below for a description of the supported disk formats. | |
50 | ||
51 | *SIZE* is the disk image size in bytes. Optional suffixes ``k`` or | |
52 | ``K`` (kilobyte, 1024) ``M`` (megabyte, 1024k) and ``G`` (gigabyte, | |
53 | 1024M) and T (terabyte, 1024G) are supported. ``b`` is ignored. | |
54 | ||
55 | *OUTPUT_FILENAME* is the destination disk image filename. | |
56 | ||
57 | *OUTPUT_FMT* is the destination format. | |
58 | ||
59 | *OPTIONS* is a comma separated list of format specific options in a | |
7f118b43 | 60 | name=value format. Use ``-o help`` for an overview of the options supported |
e13c59fa PM |
61 | by the used format or see the format descriptions below for details. |
62 | ||
63 | *SNAPSHOT_PARAM* is param used for internal snapshot, format is | |
64 | 'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'. | |
65 | ||
66 | .. | |
67 | Note the use of a new 'program'; otherwise Sphinx complains about | |
68 | the -h option appearing both in the above option list and this one. | |
69 | ||
70 | .. program:: qemu-img-common-opts | |
71 | ||
72 | .. option:: --object OBJECTDEF | |
73 | ||
74 | is a QEMU user creatable object definition. See the :manpage:`qemu(1)` | |
75 | manual page for a description of the object properties. The most common | |
76 | object type is a ``secret``, which is used to supply passwords and/or | |
77 | encryption keys. | |
78 | ||
79 | .. option:: --image-opts | |
80 | ||
81 | Indicates that the source *FILENAME* parameter is to be interpreted as a | |
82 | full option string, not a plain filename. This parameter is mutually | |
83 | exclusive with the *-f* parameter. | |
84 | ||
85 | .. option:: --target-image-opts | |
86 | ||
87 | Indicates that the OUTPUT_FILENAME parameter(s) are to be interpreted as | |
88 | a full option string, not a plain filename. This parameter is mutually | |
89 | exclusive with the *-O* parameters. It is currently required to also use | |
90 | the *-n* parameter to skip image creation. This restriction may be relaxed | |
91 | in a future release. | |
92 | ||
93 | .. option:: --force-share (-U) | |
94 | ||
95 | If specified, ``qemu-img`` will open the image in shared mode, allowing | |
96 | other QEMU processes to open it in write mode. For example, this can be used to | |
97 | get the image information (with 'info' subcommand) when the image is used by a | |
98 | running guest. Note that this could produce inconsistent results because of | |
99 | concurrent metadata changes, etc. This option is only allowed when opening | |
100 | images in read-only mode. | |
101 | ||
102 | .. option:: --backing-chain | |
103 | ||
104 | Will enumerate information about backing files in a disk image chain. Refer | |
105 | below for further description. | |
106 | ||
107 | .. option:: -c | |
108 | ||
a675ca4c KW |
109 | Indicates that target image must be compressed (qcow/qcow2 and vmdk with |
110 | streamOptimized subformat only). | |
111 | ||
112 | For qcow2, the compression algorithm can be specified with the ``-o | |
113 | compression_type=...`` option (see below). | |
e13c59fa PM |
114 | |
115 | .. option:: -h | |
116 | ||
117 | With or without a command, shows help and lists the supported formats. | |
118 | ||
119 | .. option:: -p | |
120 | ||
121 | Display progress bar (compare, convert and rebase commands only). | |
122 | If the *-p* option is not used for a command that supports it, the | |
123 | progress is reported when the process receives a ``SIGUSR1`` or | |
124 | ``SIGINFO`` signal. | |
125 | ||
126 | .. option:: -q | |
127 | ||
128 | Quiet mode - do not print any output (except errors). There's no progress bar | |
129 | in case both *-q* and *-p* options are used. | |
130 | ||
131 | .. option:: -S SIZE | |
132 | ||
133 | Indicates the consecutive number of bytes that must contain only zeros | |
c5ba6219 PMD |
134 | for ``qemu-img`` to create a sparse image during conversion. This value is |
135 | rounded down to the nearest 512 bytes. You may use the common size suffixes | |
136 | like ``k`` for kilobytes. | |
e13c59fa PM |
137 | |
138 | .. option:: -t CACHE | |
139 | ||
140 | Specifies the cache mode that should be used with the (destination) file. See | |
141 | the documentation of the emulator's ``-drive cache=...`` option for allowed | |
142 | values. | |
143 | ||
144 | .. option:: -T SRC_CACHE | |
145 | ||
146 | Specifies the cache mode that should be used with the source file(s). See | |
147 | the documentation of the emulator's ``-drive cache=...`` option for allowed | |
148 | values. | |
149 | ||
e13c59fa PM |
150 | Parameters to compare subcommand: |
151 | ||
152 | .. program:: qemu-img-compare | |
153 | ||
154 | .. option:: -f | |
155 | ||
156 | First image format | |
157 | ||
158 | .. option:: -F | |
159 | ||
160 | Second image format | |
161 | ||
162 | .. option:: -s | |
163 | ||
164 | Strict mode - fail on different image size or sector allocation | |
165 | ||
166 | Parameters to convert subcommand: | |
167 | ||
168 | .. program:: qemu-img-convert | |
169 | ||
15e39ad9 EB |
170 | .. option:: --bitmaps |
171 | ||
172 | Additionally copy all persistent bitmaps from the top layer of the source | |
173 | ||
e13c59fa PM |
174 | .. option:: -n |
175 | ||
176 | Skip the creation of the target volume | |
177 | ||
178 | .. option:: -m | |
179 | ||
180 | Number of parallel coroutines for the convert process | |
181 | ||
182 | .. option:: -W | |
183 | ||
184 | Allow out-of-order writes to the destination. This option improves performance, | |
185 | but is only recommended for preallocated devices like host devices or other | |
186 | raw block devices. | |
187 | ||
188 | .. option:: -C | |
189 | ||
190 | Try to use copy offloading to move data from source image to target. This may | |
191 | improve performance if the data is remote, such as with NFS or iSCSI backends, | |
192 | but will not automatically sparsify zero sectors, and may result in a fully | |
193 | allocated target image depending on the host support for getting allocation | |
194 | information. | |
195 | ||
0c8c4895 ZL |
196 | .. option:: -r |
197 | ||
198 | Rate limit for the convert process | |
199 | ||
e13c59fa PM |
200 | .. option:: --salvage |
201 | ||
202 | Try to ignore I/O errors when reading. Unless in quiet mode (``-q``), errors | |
203 | will still be printed. Areas that cannot be read from the source will be | |
204 | treated as containing only zeroes. | |
205 | ||
168468fe DE |
206 | .. option:: --target-is-zero |
207 | ||
208 | Assume that reading the destination image will always return | |
209 | zeros. This parameter is mutually exclusive with a destination image | |
210 | that has a backing file. It is required to also use the ``-n`` | |
211 | parameter to skip image creation. | |
212 | ||
e13c59fa PM |
213 | Parameters to dd subcommand: |
214 | ||
215 | .. program:: qemu-img-dd | |
216 | ||
217 | .. option:: bs=BLOCK_SIZE | |
218 | ||
219 | Defines the block size | |
220 | ||
221 | .. option:: count=BLOCKS | |
222 | ||
223 | Sets the number of input blocks to copy | |
224 | ||
225 | .. option:: if=INPUT | |
226 | ||
227 | Sets the input file | |
228 | ||
229 | .. option:: of=OUTPUT | |
230 | ||
231 | Sets the output file | |
232 | ||
233 | .. option:: skip=BLOCKS | |
234 | ||
235 | Sets the number of input blocks to skip | |
236 | ||
6edb788f EB |
237 | Parameters to snapshot subcommand: |
238 | ||
239 | .. program:: qemu-img-snapshot | |
240 | ||
241 | .. option:: snapshot | |
242 | ||
243 | Is the name of the snapshot to create, apply or delete | |
244 | ||
245 | .. option:: -a | |
246 | ||
247 | Applies a snapshot (revert disk to saved state) | |
248 | ||
249 | .. option:: -c | |
250 | ||
251 | Creates a snapshot | |
252 | ||
253 | .. option:: -d | |
254 | ||
255 | Deletes a snapshot | |
256 | ||
257 | .. option:: -l | |
258 | ||
259 | Lists all snapshots in the given image | |
260 | ||
e13c59fa PM |
261 | Command description: |
262 | ||
263 | .. program:: qemu-img-commands | |
264 | ||
a3579bfa | 265 | .. option:: amend [--object OBJECTDEF] [--image-opts] [-p] [-q] [-f FMT] [-t CACHE] [--force] -o OPTIONS FILENAME |
e13c59fa PM |
266 | |
267 | Amends the image format specific *OPTIONS* for the image file | |
268 | *FILENAME*. Not all file formats support this operation. | |
269 | ||
bc5ee6da EB |
270 | The set of options that can be amended are dependent on the image |
271 | format, but note that amending the backing chain relationship should | |
272 | instead be performed with ``qemu-img rebase``. | |
273 | ||
a3579bfa ML |
274 | --force allows some unsafe operations. Currently for -f luks, it allows to |
275 | erase the last encryption key, and to overwrite an active encryption key. | |
276 | ||
890fb1f6 | 277 | .. option:: bench [-c COUNT] [-d DEPTH] [-f FMT] [--flush-interval=FLUSH_INTERVAL] [-i AIO] [-n] [--no-drain] [-o OFFSET] [--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE] [-w] [-U] FILENAME |
e13c59fa PM |
278 | |
279 | Run a simple sequential I/O benchmark on the specified image. If ``-w`` is | |
280 | specified, a write test is performed, otherwise a read test is performed. | |
281 | ||
282 | A total number of *COUNT* I/O requests is performed, each *BUFFER_SIZE* | |
283 | bytes in size, and with *DEPTH* requests in parallel. The first request | |
284 | starts at the position given by *OFFSET*, each following request increases | |
285 | the current position by *STEP_SIZE*. If *STEP_SIZE* is not given, | |
286 | *BUFFER_SIZE* is used for its value. | |
287 | ||
288 | If *FLUSH_INTERVAL* is specified for a write test, the request queue is | |
289 | drained and a flush is issued before new writes are made whenever the number of | |
290 | remaining requests is a multiple of *FLUSH_INTERVAL*. If additionally | |
291 | ``--no-drain`` is specified, a flush is issued without draining the request | |
292 | queue first. | |
293 | ||
890fb1f6 JS |
294 | if ``-i`` is specified, *AIO* option can be used to specify different |
295 | AIO backends: ``threads``, ``native`` or ``io_uring``. | |
296 | ||
e13c59fa PM |
297 | If ``-n`` is specified, the native AIO backend is used if possible. On |
298 | Linux, this option only works if ``-t none`` or ``-t directsync`` is | |
299 | specified as well. | |
300 | ||
e13c59fa PM |
301 | For write tests, by default a buffer filled with zeros is written. This can be |
302 | overridden with a pattern byte specified by *PATTERN*. | |
303 | ||
3b51ab4b EB |
304 | .. option:: bitmap (--merge SOURCE | --add | --remove | --clear | --enable | --disable)... [-b SOURCE_FILE [-F SOURCE_FMT]] [-g GRANULARITY] [--object OBJECTDEF] [--image-opts | -f FMT] FILENAME BITMAP |
305 | ||
306 | Perform one or more modifications of the persistent bitmap *BITMAP* | |
307 | in the disk image *FILENAME*. The various modifications are: | |
308 | ||
309 | ``--add`` to create *BITMAP*, enabled to record future edits. | |
310 | ||
311 | ``--remove`` to remove *BITMAP*. | |
312 | ||
313 | ``--clear`` to clear *BITMAP*. | |
314 | ||
315 | ``--enable`` to change *BITMAP* to start recording future edits. | |
316 | ||
317 | ``--disable`` to change *BITMAP* to stop recording future edits. | |
318 | ||
1d745940 | 319 | ``--merge`` to merge the contents of the *SOURCE* bitmap into *BITMAP*. |
3b51ab4b EB |
320 | |
321 | Additional options include ``-g`` which sets a non-default | |
322 | *GRANULARITY* for ``--add``, and ``-b`` and ``-F`` which select an | |
323 | alternative source file for all *SOURCE* bitmaps used by | |
324 | ``--merge``. | |
325 | ||
326 | To see what bitmaps are present in an image, use ``qemu-img info``. | |
327 | ||
e13c59fa PM |
328 | .. option:: check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT] [-r [leaks | all]] [-T SRC_CACHE] [-U] FILENAME |
329 | ||
330 | Perform a consistency check on the disk image *FILENAME*. The command can | |
331 | output in the format *OFMT* which is either ``human`` or ``json``. | |
332 | The JSON output is an object of QAPI type ``ImageCheck``. | |
333 | ||
334 | If ``-r`` is specified, qemu-img tries to repair any inconsistencies found | |
335 | during the check. ``-r leaks`` repairs only cluster leaks, whereas | |
336 | ``-r all`` fixes all kinds of errors, with a higher risk of choosing the | |
337 | wrong fix or hiding corruption that has already occurred. | |
338 | ||
8e28b65f DL |
339 | Only the formats ``qcow2``, ``qed``, ``parallels``, ``vhdx``, ``vmdk`` and |
340 | ``vdi`` support consistency checks. | |
e13c59fa PM |
341 | |
342 | In case the image does not have any inconsistencies, check exits with ``0``. | |
343 | Other exit codes indicate the kind of inconsistency found or if another error | |
344 | occurred. The following table summarizes all exit codes of the check subcommand: | |
345 | ||
346 | 0 | |
347 | Check completed, the image is (now) consistent | |
348 | 1 | |
349 | Check not completed because of internal errors | |
350 | 2 | |
351 | Check completed, image is corrupted | |
352 | 3 | |
353 | Check completed, image has leaked clusters, but is not corrupted | |
354 | 63 | |
355 | Checks are not supported by the image format | |
356 | ||
357 | If ``-r`` is specified, exit codes representing the image state refer to the | |
358 | state after (the attempt at) repairing it. That is, a successful ``-r all`` | |
359 | will yield the exit code 0, independently of the image state before. | |
360 | ||
a0441b66 | 361 | .. option:: commit [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [-t CACHE] [-b BASE] [-r RATE_LIMIT] [-d] [-p] FILENAME |
e13c59fa PM |
362 | |
363 | Commit the changes recorded in *FILENAME* in its base image or backing file. | |
364 | If the backing file is smaller than the snapshot, then the backing file will be | |
365 | resized to be the same size as the snapshot. If the snapshot is smaller than | |
366 | the backing file, the backing file will not be truncated. If you want the | |
367 | backing file to match the size of the smaller snapshot, you can safely truncate | |
368 | it yourself once the commit operation successfully completes. | |
369 | ||
370 | The image *FILENAME* is emptied after the operation has succeeded. If you do | |
371 | not need *FILENAME* afterwards and intend to drop it, you may skip emptying | |
372 | *FILENAME* by specifying the ``-d`` flag. | |
373 | ||
374 | If the backing chain of the given image file *FILENAME* has more than one | |
375 | layer, the backing file into which the changes will be committed may be | |
376 | specified as *BASE* (which has to be part of *FILENAME*'s backing | |
377 | chain). If *BASE* is not specified, the immediate backing file of the top | |
378 | image (which is *FILENAME*) will be used. Note that after a commit operation | |
379 | all images between *BASE* and the top image will be invalid and may return | |
380 | garbage data when read. For this reason, ``-b`` implies ``-d`` (so that | |
381 | the top image stays valid). | |
382 | ||
a0441b66 ZL |
383 | The rate limit for the commit process is specified by ``-r``. |
384 | ||
e13c59fa PM |
385 | .. option:: compare [--object OBJECTDEF] [--image-opts] [-f FMT] [-F FMT] [-T SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1 FILENAME2 |
386 | ||
387 | Check if two images have the same content. You can compare images with | |
388 | different format or settings. | |
389 | ||
390 | The format is probed unless you specify it by ``-f`` (used for | |
391 | *FILENAME1*) and/or ``-F`` (used for *FILENAME2*) option. | |
392 | ||
393 | By default, images with different size are considered identical if the larger | |
394 | image contains only unallocated and/or zeroed sectors in the area after the end | |
395 | of the other image. In addition, if any sector is not allocated in one image | |
396 | and contains only zero bytes in the second one, it is evaluated as equal. You | |
397 | can use Strict mode by specifying the ``-s`` option. When compare runs in | |
398 | Strict mode, it fails in case image size differs or a sector is allocated in | |
399 | one image and is not allocated in the second one. | |
400 | ||
401 | By default, compare prints out a result message. This message displays | |
402 | information that both images are same or the position of the first different | |
403 | byte. In addition, result message can report different image size in case | |
404 | Strict mode is used. | |
405 | ||
406 | Compare exits with ``0`` in case the images are equal and with ``1`` | |
407 | in case the images differ. Other exit codes mean an error occurred during | |
408 | execution and standard error output should contain an error message. | |
8a8be21d | 409 | The following table summarizes all exit codes of the compare subcommand: |
e13c59fa PM |
410 | |
411 | 0 | |
99b1e646 | 412 | Images are identical (or requested help was printed) |
e13c59fa PM |
413 | 1 |
414 | Images differ | |
415 | 2 | |
416 | Error on opening an image | |
417 | 3 | |
418 | Error on checking a sector allocation | |
419 | 4 | |
420 | Error on reading data | |
421 | ||
9a5d1352 | 422 | .. option:: convert [--object OBJECTDEF] [--image-opts] [--target-image-opts] [--target-is-zero] [--bitmaps [--skip-broken-bitmaps]] [-U] [-C] [-c] [-p] [-q] [-n] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-O OUTPUT_FMT] [-B BACKING_FILE [-F BACKING_FMT]] [-o OPTIONS] [-l SNAPSHOT_PARAM] [-S SPARSE_SIZE] [-r RATE_LIMIT] [-m NUM_COROUTINES] [-W] FILENAME [FILENAME2 [...]] OUTPUT_FILENAME |
e13c59fa PM |
423 | |
424 | Convert the disk image *FILENAME* or a snapshot *SNAPSHOT_PARAM* | |
425 | to disk image *OUTPUT_FILENAME* using format *OUTPUT_FMT*. It can | |
426 | be optionally compressed (``-c`` option) or use any format specific | |
427 | options like encryption (``-o`` option). | |
428 | ||
429 | Only the formats ``qcow`` and ``qcow2`` support compression. The | |
430 | compression is read-only. It means that if a compressed sector is | |
431 | rewritten, then it is rewritten as uncompressed data. | |
432 | ||
433 | Image conversion is also useful to get smaller image when using a | |
434 | growable format such as ``qcow``: the empty sectors are detected and | |
435 | suppressed from the destination image. | |
436 | ||
437 | *SPARSE_SIZE* indicates the consecutive number of bytes (defaults to 4k) | |
c5ba6219 | 438 | that must contain only zeros for ``qemu-img`` to create a sparse image during |
e13c59fa PM |
439 | conversion. If *SPARSE_SIZE* is 0, the source will not be scanned for |
440 | unallocated or zero sectors, and the destination image will always be | |
441 | fully allocated. | |
442 | ||
443 | You can use the *BACKING_FILE* option to force the output image to be | |
444 | created as a copy on write image of the specified base image; the | |
445 | *BACKING_FILE* should have the same content as the input's base image, | |
1899bf47 | 446 | however the path, image format (as given by *BACKING_FMT*), etc may differ. |
e13c59fa PM |
447 | |
448 | If a relative path name is given, the backing file is looked up relative to | |
449 | the directory containing *OUTPUT_FILENAME*. | |
450 | ||
451 | If the ``-n`` option is specified, the target volume creation will be | |
452 | skipped. This is useful for formats such as ``rbd`` if the target | |
453 | volume has already been created with site specific options that cannot | |
c5ba6219 | 454 | be supplied through ``qemu-img``. |
e13c59fa PM |
455 | |
456 | Out of order writes can be enabled with ``-W`` to improve performance. | |
457 | This is only recommended for preallocated devices like host devices or other | |
458 | raw block devices. Out of order write does not work in combination with | |
459 | creating compressed images. | |
460 | ||
461 | *NUM_COROUTINES* specifies how many coroutines work in parallel during | |
462 | the convert process (defaults to 8). | |
463 | ||
955171e4 EB |
464 | Use of ``--bitmaps`` requests that any persistent bitmaps present in |
465 | the original are also copied to the destination. If any bitmap is | |
466 | inconsistent in the source, the conversion will fail unless | |
467 | ``--skip-broken-bitmaps`` is also specified to copy only the | |
468 | consistent bitmaps. | |
469 | ||
111fbd74 | 470 | .. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE [-F BACKING_FMT]] [-u] [-o OPTIONS] FILENAME [SIZE] |
e13c59fa PM |
471 | |
472 | Create the new disk image *FILENAME* of size *SIZE* and format | |
473 | *FMT*. Depending on the file format, you can add one or more *OPTIONS* | |
474 | that enable additional features of this format. | |
475 | ||
476 | If the option *BACKING_FILE* is specified, then the image will record | |
477 | only the differences from *BACKING_FILE*. No size needs to be specified in | |
478 | this case. *BACKING_FILE* will never be modified unless you use the | |
c5ba6219 | 479 | ``commit`` monitor command (or ``qemu-img commit``). |
e13c59fa PM |
480 | |
481 | If a relative path name is given, the backing file is looked up relative to | |
482 | the directory containing *FILENAME*. | |
483 | ||
484 | Note that a given backing file will be opened to check that it is valid. Use | |
485 | the ``-u`` option to enable unsafe backing file mode, which means that the | |
486 | image will be created even if the associated backing file cannot be opened. A | |
487 | matching backing file must be created or additional options be used to make the | |
488 | backing file specification valid when you want to use an image created this | |
489 | way. | |
490 | ||
491 | The size can also be specified using the *SIZE* option with ``-o``, | |
492 | it doesn't need to be specified separately in this case. | |
493 | ||
494 | ||
495 | .. option:: dd [--image-opts] [-U] [-f FMT] [-O OUTPUT_FMT] [bs=BLOCK_SIZE] [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT | |
496 | ||
497 | dd copies from *INPUT* file to *OUTPUT* file converting it from | |
498 | *FMT* format to *OUTPUT_FMT* format. | |
499 | ||
500 | The data is by default read and written using blocks of 512 bytes but can be | |
501 | modified by specifying *BLOCK_SIZE*. If count=\ *BLOCKS* is specified | |
502 | dd will stop reading input after reading *BLOCKS* input blocks. | |
503 | ||
504 | The size syntax is similar to :manpage:`dd(1)`'s size syntax. | |
505 | ||
506 | .. option:: info [--object OBJECTDEF] [--image-opts] [-f FMT] [--output=OFMT] [--backing-chain] [-U] FILENAME | |
507 | ||
508 | Give information about the disk image *FILENAME*. Use it in | |
509 | particular to know the size reserved on disk which can be different | |
510 | from the displayed size. If VM snapshots are stored in the disk image, | |
511 | they are displayed too. | |
512 | ||
513 | If a disk image has a backing file chain, information about each disk image in | |
514 | the chain can be recursively enumerated by using the option ``--backing-chain``. | |
515 | ||
516 | For instance, if you have an image chain like: | |
517 | ||
518 | :: | |
519 | ||
520 | base.qcow2 <- snap1.qcow2 <- snap2.qcow2 | |
521 | ||
522 | To enumerate information about each disk image in the above chain, starting from top to base, do: | |
523 | ||
524 | :: | |
525 | ||
526 | qemu-img info --backing-chain snap2.qcow2 | |
527 | ||
528 | The command can output in the format *OFMT* which is either ``human`` or | |
529 | ``json``. The JSON output is an object of QAPI type ``ImageInfo``; with | |
530 | ``--backing-chain``, it is an array of ``ImageInfo`` objects. | |
531 | ||
532 | ``--output=human`` reports the following information (for every image in the | |
533 | chain): | |
534 | ||
535 | *image* | |
536 | The image file name | |
537 | ||
538 | *file format* | |
539 | The image format | |
540 | ||
541 | *virtual size* | |
542 | The size of the guest disk | |
543 | ||
544 | *disk size* | |
545 | How much space the image file occupies on the host file system (may be | |
546 | shown as 0 if this information is unavailable, e.g. because there is no | |
547 | file system) | |
548 | ||
549 | *cluster_size* | |
550 | Cluster size of the image format, if applicable | |
551 | ||
552 | *encrypted* | |
553 | Whether the image is encrypted (only present if so) | |
554 | ||
555 | *cleanly shut down* | |
556 | This is shown as ``no`` if the image is dirty and will have to be | |
557 | auto-repaired the next time it is opened in qemu. | |
558 | ||
559 | *backing file* | |
560 | The backing file name, if present | |
561 | ||
562 | *backing file format* | |
563 | The format of the backing file, if the image enforces it | |
564 | ||
565 | *Snapshot list* | |
566 | A list of all internal snapshots | |
567 | ||
568 | *Format specific information* | |
569 | Further information whose structure depends on the image format. This | |
570 | section is a textual representation of the respective | |
571 | ``ImageInfoSpecific*`` QAPI object (e.g. ``ImageInfoSpecificQCow2`` | |
572 | for qcow2 images). | |
573 | ||
c0469496 | 574 | .. option:: map [--object OBJECTDEF] [--image-opts] [-f FMT] [--start-offset=OFFSET] [--max-length=LEN] [--output=OFMT] [-U] FILENAME |
e13c59fa PM |
575 | |
576 | Dump the metadata of image *FILENAME* and its backing file chain. | |
577 | In particular, this commands dumps the allocation state of every sector | |
578 | of *FILENAME*, together with the topmost file that allocates it in | |
579 | the backing file chain. | |
580 | ||
581 | Two option formats are possible. The default format (``human``) | |
582 | only dumps known-nonzero areas of the file. Known-zero parts of the | |
583 | file are omitted altogether, and likewise for parts that are not allocated | |
584 | throughout the chain. ``qemu-img`` output will identify a file | |
585 | from where the data can be read, and the offset in the file. Each line | |
586 | will include four fields, the first three of which are hexadecimal | |
587 | numbers. For example the first line of: | |
588 | ||
589 | :: | |
590 | ||
591 | Offset Length Mapped to File | |
592 | 0 0x20000 0x50000 /tmp/overlay.qcow2 | |
593 | 0x100000 0x10000 0x95380000 /tmp/backing.qcow2 | |
594 | ||
595 | means that 0x20000 (131072) bytes starting at offset 0 in the image are | |
596 | available in /tmp/overlay.qcow2 (opened in ``raw`` format) starting | |
597 | at offset 0x50000 (327680). Data that is compressed, encrypted, or | |
598 | otherwise not available in raw format will cause an error if ``human`` | |
599 | format is in use. Note that file names can include newlines, thus it is | |
600 | not safe to parse this output format in scripts. | |
601 | ||
602 | The alternative format ``json`` will return an array of dictionaries | |
603 | in JSON format. It will include similar information in | |
604 | the ``start``, ``length``, ``offset`` fields; | |
605 | it will also include other more specific information: | |
606 | ||
a275b452 EB |
607 | - boolean field ``data``: true if the sectors contain actual data, |
608 | false if the sectors are either unallocated or stored as optimized | |
609 | all-zero clusters | |
610 | - boolean field ``zero``: true if the data is known to read as zero | |
611 | - boolean field ``present``: true if the data belongs to the backing | |
612 | chain, false if rebasing the backing chain onto a deeper file | |
613 | would pick up data from the deeper file; | |
614 | - integer field ``depth``: the depth within the backing chain at | |
615 | which the data was resolved; for example, a depth of 2 refers to | |
616 | the backing file of the backing file of *FILENAME*. | |
e13c59fa PM |
617 | |
618 | In JSON format, the ``offset`` field is optional; it is absent in | |
619 | cases where ``human`` format would omit the entry or exit with an error. | |
620 | If ``data`` is false and the ``offset`` field is present, the | |
621 | corresponding sectors in the file are not yet in use, but they are | |
622 | preallocated. | |
623 | ||
624 | For more information, consult ``include/block/block.h`` in QEMU's | |
625 | source code. | |
626 | ||
627 | .. option:: measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--object OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME] | |
628 | ||
629 | Calculate the file size required for a new image. This information | |
630 | can be used to size logical volumes or SAN LUNs appropriately for | |
631 | the image that will be placed in them. The values reported are | |
632 | guaranteed to be large enough to fit the image. The command can | |
633 | output in the format *OFMT* which is either ``human`` or ``json``. | |
634 | The JSON output is an object of QAPI type ``BlockMeasureInfo``. | |
635 | ||
636 | If the size *N* is given then act as if creating a new empty image file | |
637 | using ``qemu-img create``. If *FILENAME* is given then act as if | |
638 | converting an existing image file using ``qemu-img convert``. The format | |
639 | of the new file is given by *OUTPUT_FMT* while the format of an existing | |
640 | file is given by *FMT*. | |
641 | ||
642 | A snapshot in an existing image can be specified using *SNAPSHOT_PARAM*. | |
643 | ||
644 | The following fields are reported: | |
645 | ||
646 | :: | |
647 | ||
648 | required size: 524288 | |
649 | fully allocated size: 1074069504 | |
5d72c68b | 650 | bitmaps size: 0 |
e13c59fa PM |
651 | |
652 | The ``required size`` is the file size of the new image. It may be smaller | |
653 | than the virtual disk size if the image format supports compact representation. | |
654 | ||
655 | The ``fully allocated size`` is the file size of the new image once data has | |
656 | been written to all sectors. This is the maximum size that the image file can | |
657 | occupy with the exception of internal snapshots, dirty bitmaps, vmstate data, | |
658 | and other advanced image format features. | |
659 | ||
5d72c68b EB |
660 | The ``bitmaps size`` is the additional size required in order to |
661 | copy bitmaps from a source image in addition to the guest-visible | |
662 | data; the line is omitted if either source or destination lacks | |
663 | bitmap support, or 0 if bitmaps are supported but there is nothing | |
664 | to copy. | |
665 | ||
e13c59fa PM |
666 | .. option:: snapshot [--object OBJECTDEF] [--image-opts] [-U] [-q] [-l | -a SNAPSHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME |
667 | ||
668 | List, apply, create or delete snapshots in image *FILENAME*. | |
669 | ||
26ea2789 | 670 | .. option:: rebase [--object OBJECTDEF] [--image-opts] [-U] [-q] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-p] [-u] [-c] -b BACKING_FILE [-F BACKING_FMT] FILENAME |
e13c59fa PM |
671 | |
672 | Changes the backing file of an image. Only the formats ``qcow2`` and | |
673 | ``qed`` support changing the backing file. | |
674 | ||
675 | The backing file is changed to *BACKING_FILE* and (if the image format of | |
676 | *FILENAME* supports this) the backing file format is changed to | |
677 | *BACKING_FMT*. If *BACKING_FILE* is specified as "" (the empty | |
678 | string), then the image is rebased onto no backing file (i.e. it will exist | |
679 | independently of any backing file). | |
680 | ||
681 | If a relative path name is given, the backing file is looked up relative to | |
682 | the directory containing *FILENAME*. | |
683 | ||
684 | *CACHE* specifies the cache mode to be used for *FILENAME*, whereas | |
685 | *SRC_CACHE* specifies the cache mode for reading backing files. | |
686 | ||
687 | There are two different modes in which ``rebase`` can operate: | |
688 | ||
689 | Safe mode | |
690 | This is the default mode and performs a real rebase operation. The | |
c5ba6219 | 691 | new backing file may differ from the old one and ``qemu-img rebase`` |
e13c59fa PM |
692 | will take care of keeping the guest-visible content of *FILENAME* |
693 | unchanged. | |
694 | ||
695 | In order to achieve this, any clusters that differ between | |
696 | *BACKING_FILE* and the old backing file of *FILENAME* are merged | |
26ea2789 AD |
697 | into *FILENAME* before actually changing the backing file. With the |
698 | ``-c`` option specified, the clusters which are being merged (but not | |
699 | the entire *FILENAME* image) are compressed when written. | |
e13c59fa PM |
700 | |
701 | Note that the safe mode is an expensive operation, comparable to | |
702 | converting an image. It only works if the old backing file still | |
703 | exists. | |
704 | ||
705 | Unsafe mode | |
c5ba6219 | 706 | ``qemu-img`` uses the unsafe mode if ``-u`` is specified. In this |
e13c59fa PM |
707 | mode, only the backing file name and format of *FILENAME* is changed |
708 | without any checks on the file contents. The user must take care of | |
709 | specifying the correct new backing file, or the guest-visible | |
710 | content of the image will be corrupted. | |
711 | ||
712 | This mode is useful for renaming or moving the backing file to | |
713 | somewhere else. It can be used without an accessible old backing | |
714 | file, i.e. you can use it to fix an image whose backing file has | |
715 | already been moved/renamed. | |
716 | ||
717 | You can use ``rebase`` to perform a "diff" operation on two | |
718 | disk images. This can be useful when you have copied or cloned | |
719 | a guest, and you want to get back to a thin image on top of a | |
720 | template or base image. | |
721 | ||
722 | Say that ``base.img`` has been cloned as ``modified.img`` by | |
723 | copying it, and that the ``modified.img`` guest has run so there | |
724 | are now some changes compared to ``base.img``. To construct a thin | |
725 | image called ``diff.qcow2`` that contains just the differences, do: | |
726 | ||
727 | :: | |
728 | ||
729 | qemu-img create -f qcow2 -b modified.img diff.qcow2 | |
730 | qemu-img rebase -b base.img diff.qcow2 | |
731 | ||
732 | At this point, ``modified.img`` can be discarded, since | |
733 | ``base.img + diff.qcow2`` contains the same information. | |
734 | ||
735 | .. option:: resize [--object OBJECTDEF] [--image-opts] [-f FMT] [--preallocation=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE | |
736 | ||
737 | Change the disk image as if it had been created with *SIZE*. | |
738 | ||
739 | Before using this command to shrink a disk image, you MUST use file system and | |
740 | partitioning tools inside the VM to reduce allocated file systems and partition | |
741 | sizes accordingly. Failure to do so will result in data loss! | |
742 | ||
743 | When shrinking images, the ``--shrink`` option must be given. This informs | |
c5ba6219 | 744 | ``qemu-img`` that the user acknowledges all loss of data beyond the truncated |
e13c59fa PM |
745 | image's end. |
746 | ||
747 | After using this command to grow a disk image, you must use file system and | |
748 | partitioning tools inside the VM to actually begin using the new space on the | |
749 | device. | |
750 | ||
751 | When growing an image, the ``--preallocation`` option may be used to specify | |
752 | how the additional image area should be allocated on the host. See the format | |
753 | description in the :ref:`notes` section which values are allowed. Using this | |
754 | option may result in slightly more data being allocated than necessary. | |
755 | ||
756 | .. _notes: | |
757 | ||
758 | Notes | |
759 | ----- | |
760 | ||
761 | Supported image file formats: | |
762 | ||
763 | ``raw`` | |
764 | ||
765 | Raw disk image format (default). This format has the advantage of | |
766 | being simple and easily exportable to all other emulators. If your | |
767 | file system supports *holes* (for example in ext2 or ext3 on | |
768 | Linux or NTFS on Windows), then only the written sectors will reserve | |
769 | space. Use ``qemu-img info`` to know the real size used by the | |
770 | image or ``ls -ls`` on Unix/Linux. | |
771 | ||
772 | Supported options: | |
773 | ||
774 | ``preallocation`` | |
775 | Preallocation mode (allowed values: ``off``, ``falloc``, | |
776 | ``full``). ``falloc`` mode preallocates space for image by | |
777 | calling ``posix_fallocate()``. ``full`` mode preallocates space | |
778 | for image by writing data to underlying storage. This data may or | |
779 | may not be zero, depending on the storage location. | |
780 | ||
781 | ``qcow2`` | |
782 | ||
783 | QEMU image format, the most versatile format. Use it to have smaller | |
784 | images (useful if your filesystem does not supports holes, for example | |
a675ca4c | 785 | on Windows), optional AES encryption, zlib or zstd based compression and |
e13c59fa PM |
786 | support of multiple VM snapshots. |
787 | ||
788 | Supported options: | |
789 | ||
790 | ``compat`` | |
791 | Determines the qcow2 version to use. ``compat=0.10`` uses the | |
792 | traditional image format that can be read by any QEMU since 0.10. | |
793 | ``compat=1.1`` enables image format extensions that only QEMU 1.1 and | |
794 | newer understand (this is the default). Amongst others, this includes zero | |
795 | clusters, which allow efficient copy-on-read for sparse images. | |
796 | ||
797 | ``backing_file`` | |
798 | File name of a base image (see ``create`` subcommand) | |
799 | ||
800 | ``backing_fmt`` | |
801 | Image format of the base image | |
802 | ||
a675ca4c KW |
803 | ``compression_type`` |
804 | This option configures which compression algorithm will be used for | |
805 | compressed clusters on the image. Note that setting this option doesn't yet | |
806 | cause the image to actually receive compressed writes. It is most commonly | |
807 | used with the ``-c`` option of ``qemu-img convert``, but can also be used | |
808 | with the ``compress`` filter driver or backup block jobs with compression | |
809 | enabled. | |
810 | ||
811 | Valid values are ``zlib`` and ``zstd``. For images that use | |
812 | ``compat=0.10``, only ``zlib`` compression is available. | |
813 | ||
e13c59fa PM |
814 | ``encryption`` |
815 | If this option is set to ``on``, the image is encrypted with | |
816 | 128-bit AES-CBC. | |
817 | ||
818 | The use of encryption in qcow and qcow2 images is considered to be | |
819 | flawed by modern cryptography standards, suffering from a number | |
820 | of design problems: | |
821 | ||
822 | - The AES-CBC cipher is used with predictable initialization | |
823 | vectors based on the sector number. This makes it vulnerable to | |
824 | chosen plaintext attacks which can reveal the existence of | |
825 | encrypted data. | |
826 | ||
827 | - The user passphrase is directly used as the encryption key. A | |
828 | poorly chosen or short passphrase will compromise the security | |
829 | of the encryption. | |
830 | ||
831 | - In the event of the passphrase being compromised there is no way | |
832 | to change the passphrase to protect data in any qcow images. The | |
833 | files must be cloned, using a different encryption passphrase in | |
834 | the new file. The original file must then be securely erased | |
835 | using a program like shred, though even this is ineffective with | |
836 | many modern storage technologies. | |
837 | ||
838 | - Initialization vectors used to encrypt sectors are based on the | |
839 | guest virtual sector number, instead of the host physical | |
840 | sector. When a disk image has multiple internal snapshots this | |
841 | means that data in multiple physical sectors is encrypted with | |
842 | the same initialization vector. With the CBC mode, this opens | |
843 | the possibility of watermarking attacks if the attack can | |
844 | collect multiple sectors encrypted with the same IV and some | |
845 | predictable data. Having multiple qcow2 images with the same | |
846 | passphrase also exposes this weakness since the passphrase is | |
847 | directly used as the key. | |
848 | ||
849 | Use of qcow / qcow2 encryption is thus strongly discouraged. Users are | |
850 | recommended to use an alternative encryption technology such as the | |
851 | Linux dm-crypt / LUKS system. | |
852 | ||
853 | ``cluster_size`` | |
854 | Changes the qcow2 cluster size (must be between 512 and | |
855 | 2M). Smaller cluster sizes can improve the image file size whereas | |
856 | larger cluster sizes generally provide better performance. | |
857 | ||
858 | ``preallocation`` | |
859 | Preallocation mode (allowed values: ``off``, ``metadata``, | |
860 | ``falloc``, ``full``). An image with preallocated metadata is | |
861 | initially larger but can improve performance when the image needs | |
862 | to grow. ``falloc`` and ``full`` preallocations are like the same | |
863 | options of ``raw`` format, but sets up metadata also. | |
864 | ||
865 | ``lazy_refcounts`` | |
866 | If this option is set to ``on``, reference count updates are | |
867 | postponed with the goal of avoiding metadata I/O and improving | |
868 | performance. This is particularly interesting with | |
869 | ``cache=writethrough`` which doesn't batch metadata | |
870 | updates. The tradeoff is that after a host crash, the reference | |
871 | count tables must be rebuilt, i.e. on the next open an (automatic) | |
872 | ``qemu-img check -r all`` is required, which may take some time. | |
873 | ||
874 | This option can only be enabled if ``compat=1.1`` is specified. | |
875 | ||
876 | ``nocow`` | |
877 | If this option is set to ``on``, it will turn off COW of the file. It's | |
878 | only valid on btrfs, no effect on other file systems. | |
879 | ||
880 | Btrfs has low performance when hosting a VM image file, even more | |
881 | when the guest on the VM also using btrfs as file system. Turning | |
882 | off COW is a way to mitigate this bad performance. Generally there | |
883 | are two ways to turn off COW on btrfs: | |
884 | ||
885 | - Disable it by mounting with nodatacow, then all newly created files | |
886 | will be NOCOW | |
887 | - For an empty file, add the NOCOW file attribute. That's what this | |
888 | option does. | |
889 | ||
890 | Note: this option is only valid to new or empty files. If there is | |
891 | an existing file which is COW and has data blocks already, it | |
892 | couldn't be changed to NOCOW by setting ``nocow=on``. One can | |
893 | issue ``lsattr filename`` to check if the NOCOW flag is set or not | |
894 | (Capital 'C' is NOCOW flag). | |
895 | ||
d65173f9 CK |
896 | ``data_file`` |
897 | Filename where all guest data will be stored. If this option is used, | |
898 | the qcow2 file will only contain the image's metadata. | |
899 | ||
900 | Note: Data loss will occur if the given filename already exists when | |
901 | using this option with ``qemu-img create`` since ``qemu-img`` will create | |
902 | the data file anew, overwriting the file's original contents. To simply | |
903 | update the reference to point to the given pre-existing file, use | |
904 | ``qemu-img amend``. | |
905 | ||
906 | ``data_file_raw`` | |
907 | If this option is set to ``on``, QEMU will always keep the external data | |
908 | file consistent as a standalone read-only raw image. | |
909 | ||
910 | It does this by forwarding all write accesses to the qcow2 file through to | |
911 | the raw data file, including their offsets. Therefore, data that is visible | |
912 | on the qcow2 node (i.e., to the guest) at some offset is visible at the same | |
913 | offset in the raw data file. This results in a read-only raw image. Writes | |
914 | that bypass the qcow2 metadata may corrupt the qcow2 metadata because the | |
915 | out-of-band writes may result in the metadata falling out of sync with the | |
916 | raw image. | |
917 | ||
918 | If this option is ``off``, QEMU will use the data file to store data in an | |
919 | arbitrary manner. The file’s content will not make sense without the | |
920 | accompanying qcow2 metadata. Where data is written will have no relation to | |
921 | its offset as seen by the guest, and some writes (specifically zero writes) | |
922 | may not be forwarded to the data file at all, but will only be handled by | |
923 | modifying qcow2 metadata. | |
924 | ||
925 | This option can only be enabled if ``data_file`` is set. | |
926 | ||
e13c59fa PM |
927 | ``Other`` |
928 | ||
929 | QEMU also supports various other image file formats for | |
930 | compatibility with older QEMU versions or other hypervisors, | |
931 | including VMDK, VDI, VHD (vpc), VHDX, qcow1 and QED. For a full list | |
932 | of supported formats see ``qemu-img --help``. For a more detailed | |
933 | description of these formats, see the QEMU block drivers reference | |
934 | documentation. | |
935 | ||
936 | The main purpose of the block drivers for these formats is image | |
937 | conversion. For running VMs, it is recommended to convert the disk | |
938 | images to either raw or qcow2 in order to achieve good performance. |