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