]> git.proxmox.com Git - mirror_qemu.git/blame - qemu-img.texi
pc-bios/s390-ccw: Remove duplicate blk_factor adjustment
[mirror_qemu.git] / qemu-img.texi
CommitLineData
acd935ef
FB
1@example
2@c man begin SYNOPSIS
10985131 3@command{qemu-img} [@var{standard} @var{options}] @var{command} [@var{command} @var{options}]
acd935ef
FB
4@c man end
5@end example
6
48467328
KW
7@c man begin DESCRIPTION
8qemu-img allows you to create, convert and modify images offline. It can handle
9all image formats supported by QEMU.
10
11@b{Warning:} Never use qemu-img to modify images in use by a running virtual
12machine or any other process; this may destroy the image. Also, be aware that
13querying an image that is being modified by another process may encounter
14inconsistent state.
15@c man end
16
acd935ef
FB
17@c man begin OPTIONS
18
10985131
DL
19Standard options:
20@table @option
21@item -h, --help
22Display this help and exit
23@item -V, --version
24Display version information and exit
06a1e0c1
DL
25@item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
26@findex --trace
27@include qemu-option-trace.texi
10985131
DL
28@end table
29
acd935ef 30The following commands are supported:
153859be
SB
31
32@include qemu-img-cmds.texi
acd935ef
FB
33
34Command parameters:
35@table @var
36@item filename
37 is a disk image filename
3babeb15
DB
38
39@item --object @var{objectdef}
40
41is a QEMU user creatable object definition. See the @code{qemu(1)} manual
42page for a description of the object properties. The most common object
43type is a @code{secret}, which is used to supply passwords and/or encryption
44keys.
45
eb769f74
DB
46@item --image-opts
47
48Indicates that the @var{filename} parameter is to be interpreted as a
49full option string, not a plain filename. This parameter is mutually
50exclusive with the @var{-f} and @var{-F} parameters.
51
5fafdf24 52@item fmt
f932c040
KW
53is the disk image format. It is guessed automatically in most cases. See below
54for a description of the supported disk formats.
acd935ef 55
e5357560
KC
56@item --backing-chain
57will enumerate information about backing files in a disk image chain. Refer
58below for further description.
59
5fafdf24 60@item size
eff44266
KW
61is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
62(kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)
63and T (terabyte, 1024G) are supported. @code{b} is ignored.
acd935ef
FB
64
65@item output_filename
5fafdf24 66is the destination disk image filename
acd935ef
FB
67
68@item output_fmt
69 is the destination format
eff44266
KW
70@item options
71is a comma separated list of format specific options in a
72name=value format. Use @code{-o ?} for an overview of the options supported
3e032364 73by the used format or see the format descriptions below for details.
ef80654d
WX
74@item snapshot_param
75is param used for internal snapshot, format is
76'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'
77@item snapshot_id_or_name
78is deprecated, use snapshot_param instead
acd935ef
FB
79
80@item -c
81indicates that target image must be compressed (qcow format only)
d2c639d6
BS
82@item -h
83with or without a command shows help and lists the supported formats
aaf55b47 84@item -p
0e3bd993
KW
85display progress bar (compare, convert and rebase commands only).
86If the @var{-p} option is not used for a command that supports it, the
262fbae6
HR
87progress is reported when the process receives a @code{SIGUSR1} or
88@code{SIGINFO} signal.
f382d43a
MR
89@item -q
90Quiet mode - do not print any output (except errors). There's no progress bar
91in case both @var{-q} and @var{-p} options are used.
a22f123c
KW
92@item -S @var{size}
93indicates the consecutive number of bytes that must contain only zeros
94for qemu-img to create a sparse image during conversion. This value is rounded
95down to the nearest 512 bytes. You may use the common size suffixes like
96@code{k} for kilobytes.
3763f26f
KW
97@item -t @var{cache}
98specifies the cache mode that should be used with the (destination) file. See
99the documentation of the emulator's @code{-drive cache=...} option for allowed
100values.
40055951 101@item -T @var{src_cache}
bb87fdf8
SH
102specifies the cache mode that should be used with the source file(s). See
103the documentation of the emulator's @code{-drive cache=...} option for allowed
104values.
d2c639d6
BS
105@end table
106
107Parameters to snapshot subcommand:
108
109@table @option
110
111@item snapshot
112is the name of the snapshot to create, apply or delete
113@item -a
114applies a snapshot (revert disk to saved state)
115@item -c
116creates a snapshot
117@item -d
118deletes a snapshot
119@item -l
120lists all snapshots in the given image
acd935ef
FB
121@end table
122
d14ed18c
MR
123Parameters to compare subcommand:
124
125@table @option
126
127@item -f
128First image format
129@item -F
130Second image format
131@item -s
b6af0975 132Strict mode - fail on different image size or sector allocation
d14ed18c
MR
133@end table
134
b2e10493
AD
135Parameters to convert subcommand:
136
137@table @option
138
139@item -n
140Skip the creation of the target volume
2d9187bc
PL
141@item -m
142Number of parallel coroutines for the convert process
143@item -W
144Allow out-of-order writes to the destination. This option improves performance,
145but is only recommended for preallocated devices like host devices or other
146raw block devices.
b2e10493
AD
147@end table
148
86ce1f6e
RS
149Parameters to dd subcommand:
150
151@table @option
152
153@item bs=@var{block_size}
154defines the block size
155@item count=@var{blocks}
156sets the number of input blocks to copy
157@item if=@var{input}
158sets the input file
159@item of=@var{output}
160sets the output file
f7c15533
RS
161@item skip=@var{blocks}
162sets the number of input blocks to skip
86ce1f6e
RS
163@end table
164
acd935ef
FB
165Command description:
166
167@table @option
55d539c8 168@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] @var{filename}
b6133b8c 169
b6495fa8
KW
170Run a simple sequential I/O benchmark on the specified image. If @code{-w} is
171specified, a write test is performed, otherwise a read test is performed.
172
173A total number of @var{count} I/O requests is performed, each @var{buffer_size}
d3199a31 174bytes in size, and with @var{depth} requests in parallel. The first request
83de9be0
KW
175starts at the position given by @var{offset}, each following request increases
176the current position by @var{step_size}. If @var{step_size} is not given,
177@var{buffer_size} is used for its value.
b6133b8c 178
55d539c8
KW
179If @var{flush_interval} is specified for a write test, the request queue is
180drained and a flush is issued before new writes are made whenever the number of
181remaining requests is a multiple of @var{flush_interval}. If additionally
182@code{--no-drain} is specified, a flush is issued without draining the request
183queue first.
184
b6133b8c
KW
185If @code{-n} is specified, the native AIO backend is used if possible. On
186Linux, this option only works if @code{-t none} or @code{-t directsync} is
187specified as well.
188
b6495fa8
KW
189For write tests, by default a buffer filled with zeros is written. This can be
190overridden with a pattern byte specified by @var{pattern}.
191
40055951 192@item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] @var{filename}
e6184690 193
8599ea4c
FS
194Perform a consistency check on the disk image @var{filename}. The command can
195output in the format @var{ofmt} which is either @code{human} or @code{json}.
e6184690 196
4534ff54
KW
197If @code{-r} is specified, qemu-img tries to repair any inconsistencies found
198during the check. @code{-r leaks} repairs only cluster leaks, whereas
199@code{-r all} fixes all kinds of errors, with a higher risk of choosing the
0546b8c2 200wrong fix or hiding corruption that has already occurred.
4534ff54 201
e6184690
KW
202Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
203consistency checks.
204
d6635c4d
HR
205In case the image does not have any inconsistencies, check exits with @code{0}.
206Other exit codes indicate the kind of inconsistency found or if another error
207occurred. The following table summarizes all exit codes of the check subcommand:
208
209@table @option
210
211@item 0
212Check completed, the image is (now) consistent
213@item 1
214Check not completed because of internal errors
215@item 2
216Check completed, image is corrupted
217@item 3
218Check completed, image has leaked clusters, but is not corrupted
219@item 63
220Checks are not supported by the image format
221
222@end table
223
224If @code{-r} is specified, exit codes representing the image state refer to the
225state after (the attempt at) repairing it. That is, a successful @code{-r all}
226will yield the exit code 0, independently of the image state before.
227
2b4c0a20 228@item create [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-o @var{options}] @var{filename} [@var{size}]
acd935ef
FB
229
230Create the new disk image @var{filename} of size @var{size} and format
8063d0fe
KW
231@var{fmt}. Depending on the file format, you can add one or more @var{options}
232that enable additional features of this format.
acd935ef 233
8063d0fe
KW
234If the option @var{backing_file} is specified, then the image will record
235only the differences from @var{backing_file}. No size needs to be specified in
236this case. @var{backing_file} will never be modified unless you use the
237@code{commit} monitor command (or qemu-img commit).
acd935ef 238
eff44266
KW
239The size can also be specified using the @var{size} option with @code{-o},
240it doesn't need to be specified separately in this case.
241
1b22bffd 242@item commit [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
acd935ef 243
37222900
JC
244Commit the changes recorded in @var{filename} in its base image or backing file.
245If the backing file is smaller than the snapshot, then the backing file will be
246resized to be the same size as the snapshot. If the snapshot is smaller than
247the backing file, the backing file will not be truncated. If you want the
248backing file to match the size of the smaller snapshot, you can safely truncate
249it yourself once the commit operation successfully completes.
acd935ef 250
9a86fe48
HR
251The image @var{filename} is emptied after the operation has succeeded. If you do
252not need @var{filename} afterwards and intend to drop it, you may skip emptying
253@var{filename} by specifying the @code{-d} flag.
254
1b22bffd
HR
255If the backing chain of the given image file @var{filename} has more than one
256layer, the backing file into which the changes will be committed may be
257specified as @var{base} (which has to be part of @var{filename}'s backing
258chain). If @var{base} is not specified, the immediate backing file of the top
259image (which is @var{filename}) will be used. For reasons of consistency,
260explicitly specifying @var{base} will always imply @code{-d} (since emptying an
261image after committing to an indirect backing file would lead to different data
262being read from the image due to content in the intermediate backing chain
263overruling the commit target).
264
40055951 265@item compare [-f @var{fmt}] [-F @var{fmt}] [-T @var{src_cache}] [-p] [-s] [-q] @var{filename1} @var{filename2}
d14ed18c
MR
266
267Check if two images have the same content. You can compare images with
268different format or settings.
269
270The format is probed unless you specify it by @var{-f} (used for
271@var{filename1}) and/or @var{-F} (used for @var{filename2}) option.
272
273By default, images with different size are considered identical if the larger
274image contains only unallocated and/or zeroed sectors in the area after the end
275of the other image. In addition, if any sector is not allocated in one image
276and contains only zero bytes in the second one, it is evaluated as equal. You
277can use Strict mode by specifying the @var{-s} option. When compare runs in
278Strict mode, it fails in case image size differs or a sector is allocated in
279one image and is not allocated in the second one.
280
281By default, compare prints out a result message. This message displays
282information that both images are same or the position of the first different
283byte. In addition, result message can report different image size in case
284Strict mode is used.
285
286Compare exits with @code{0} in case the images are equal and with @code{1}
287in case the images differ. Other exit codes mean an error occurred during
288execution and standard error output should contain an error message.
289The following table sumarizes all exit codes of the compare subcommand:
290
291@table @option
292
293@item 0
294Images are identical
295@item 1
296Images differ
297@item 2
298Error on opening an image
299@item 3
300Error on checking a sector allocation
301@item 4
302Error on reading data
303
304@end table
305
2b4c0a20 306@item convert [-c] [-p] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}] [-s @var{snapshot_id_or_name}] [-l @var{snapshot_param}] [-m @var{num_coroutines}] [-W] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename}
acd935ef 307
ef80654d
WX
308Convert the disk image @var{filename} or a snapshot @var{snapshot_param}(@var{snapshot_id_or_name} is deprecated)
309to disk image @var{output_filename} using format @var{output_fmt}. It can be optionally compressed (@code{-c}
eff44266 310option) or use any format specific options like encryption (@code{-o} option).
acd935ef 311
8063d0fe 312Only the formats @code{qcow} and @code{qcow2} support compression. The
acd935ef
FB
313compression is read-only. It means that if a compressed sector is
314rewritten, then it is rewritten as uncompressed data.
315
acd935ef 316Image conversion is also useful to get smaller image when using a
550830f9
SH
317growable format such as @code{qcow}: the empty sectors are detected and
318suppressed from the destination image.
acd935ef 319
11b6699a
PL
320@var{sparse_size} indicates the consecutive number of bytes (defaults to 4k)
321that must contain only zeros for qemu-img to create a sparse image during
322conversion. If @var{sparse_size} is 0, the source will not be scanned for
323unallocated or zero sectors, and the destination image will always be
324fully allocated.
325
8063d0fe
KW
326You can use the @var{backing_file} option to force the output image to be
327created as a copy on write image of the specified base image; the
328@var{backing_file} should have the same content as the input's base image,
329however the path, image format, etc may differ.
330
b2e10493
AD
331If the @code{-n} option is specified, the target volume creation will be
332skipped. This is useful for formats such as @code{rbd} if the target
333volume has already been created with site specific options that cannot
334be supplied through qemu-img.
335
2d9187bc
PL
336Out of order writes can be enabled with @code{-W} to improve performance.
337This is only recommended for preallocated devices like host devices or other
338raw block devices. Out of order write does not work in combination with
339creating compressed images.
340
341@var{num_coroutines} specifies how many coroutines work in parallel during
342the convert process (defaults to 8).
343
f7c15533 344@item dd [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output}
86ce1f6e
RS
345
346Dd copies from @var{input} file to @var{output} file converting it from
347@var{fmt} format to @var{output_fmt} format.
348
349The data is by default read and written using blocks of 512 bytes but can be
350modified by specifying @var{block_size}. If count=@var{blocks} is specified
351dd will stop reading input after reading @var{blocks} input blocks.
352
353The size syntax is similar to dd(1)'s size syntax.
354
e5357560 355@item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename}
acd935ef
FB
356
357Give information about the disk image @var{filename}. Use it in
358particular to know the size reserved on disk which can be different
19d36792 359from the displayed size. If VM snapshots are stored in the disk image,
c054b3fd
BC
360they are displayed too. The command can output in the format @var{ofmt}
361which is either @code{human} or @code{json}.
d2c639d6 362
e5357560
KC
363If a disk image has a backing file chain, information about each disk image in
364the chain can be recursively enumerated by using the option @code{--backing-chain}.
365
366For instance, if you have an image chain like:
367
368@example
369base.qcow2 <- snap1.qcow2 <- snap2.qcow2
370@end example
371
372To enumerate information about each disk image in the above chain, starting from top to base, do:
373
374@example
375qemu-img info --backing-chain snap2.qcow2
376@end example
377
facd6e2b
PB
378@item map [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
379
380Dump the metadata of image @var{filename} and its backing file chain.
381In particular, this commands dumps the allocation state of every sector
382of @var{filename}, together with the topmost file that allocates it in
383the backing file chain.
384
385Two option formats are possible. The default format (@code{human})
386only dumps known-nonzero areas of the file. Known-zero parts of the
387file are omitted altogether, and likewise for parts that are not allocated
388throughout the chain. @command{qemu-img} output will identify a file
389from where the data can be read, and the offset in the file. Each line
390will include four fields, the first three of which are hexadecimal
391numbers. For example the first line of:
392@example
393Offset Length Mapped to File
3940 0x20000 0x50000 /tmp/overlay.qcow2
3950x100000 0x10000 0x95380000 /tmp/backing.qcow2
396@end example
397@noindent
398means that 0x20000 (131072) bytes starting at offset 0 in the image are
399available in /tmp/overlay.qcow2 (opened in @code{raw} format) starting
400at offset 0x50000 (327680). Data that is compressed, encrypted, or
401otherwise not available in raw format will cause an error if @code{human}
402format is in use. Note that file names can include newlines, thus it is
403not safe to parse this output format in scripts.
404
405The alternative format @code{json} will return an array of dictionaries
406in JSON format. It will include similar information in
407the @code{start}, @code{length}, @code{offset} fields;
408it will also include other more specific information:
409@itemize @minus
410@item
411whether the sectors contain actual data or not (boolean field @code{data};
412if false, the sectors are either unallocated or stored as optimized
413all-zero clusters);
414
415@item
416whether the data is known to read as zero (boolean field @code{zero});
417
418@item
419in order to make the output shorter, the target file is expressed as
420a @code{depth}; for example, a depth of 2 refers to the backing file
421of the backing file of @var{filename}.
422@end itemize
423
424In JSON format, the @code{offset} field is optional; it is absent in
425cases where @code{human} format would omit the entry or exit with an error.
426If @code{data} is false and the @code{offset} field is present, the
427corresponding sectors in the file are not yet in use, but they are
428preallocated.
429
430For more information, consult @file{include/block/block.h} in QEMU's
431source code.
432
d2c639d6
BS
433@item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
434
435List, apply, create or delete snapshots in image @var{filename}.
ae6b0ed6 436
40055951 437@item rebase [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
e6184690
KW
438
439Changes the backing file of an image. Only the formats @code{qcow2} and
440@code{qed} support changing the backing file.
441
442The backing file is changed to @var{backing_file} and (if the image format of
443@var{filename} supports this) the backing file format is changed to
a616673d
AB
444@var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty
445string), then the image is rebased onto no backing file (i.e. it will exist
446independently of any backing file).
e6184690 447
40055951 448@var{cache} specifies the cache mode to be used for @var{filename}, whereas
3ba6796d 449@var{src_cache} specifies the cache mode for reading backing files.
40055951 450
e6184690
KW
451There are two different modes in which @code{rebase} can operate:
452@table @option
453@item Safe mode
454This is the default mode and performs a real rebase operation. The new backing
455file may differ from the old one and qemu-img rebase will take care of keeping
456the guest-visible content of @var{filename} unchanged.
457
458In order to achieve this, any clusters that differ between @var{backing_file}
459and the old backing file of @var{filename} are merged into @var{filename}
460before actually changing the backing file.
461
462Note that the safe mode is an expensive operation, comparable to converting
463an image. It only works if the old backing file still exists.
464
465@item Unsafe mode
466qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the
467backing file name and format of @var{filename} is changed without any checks
468on the file contents. The user must take care of specifying the correct new
469backing file, or the guest-visible content of the image will be corrupted.
470
471This mode is useful for renaming or moving the backing file to somewhere else.
472It can be used without an accessible old backing file, i.e. you can use it to
473fix an image whose backing file has already been moved/renamed.
474@end table
475
9fda6ab1
RJ
476You can use @code{rebase} to perform a ``diff'' operation on two
477disk images. This can be useful when you have copied or cloned
478a guest, and you want to get back to a thin image on top of a
479template or base image.
480
481Say that @code{base.img} has been cloned as @code{modified.img} by
482copying it, and that the @code{modified.img} guest has run so there
483are now some changes compared to @code{base.img}. To construct a thin
484image called @code{diff.qcow2} that contains just the differences, do:
485
486@example
487qemu-img create -f qcow2 -b modified.img diff.qcow2
488qemu-img rebase -b base.img diff.qcow2
489@end example
490
491At this point, @code{modified.img} can be discarded, since
492@code{base.img + diff.qcow2} contains the same information.
493
ae6b0ed6
SH
494@item resize @var{filename} [+ | -]@var{size}
495
496Change the disk image as if it had been created with @var{size}.
497
498Before using this command to shrink a disk image, you MUST use file system and
499partitioning tools inside the VM to reduce allocated file systems and partition
500sizes accordingly. Failure to do so will result in data loss!
501
502After using this command to grow a disk image, you must use file system and
503partitioning tools inside the VM to actually begin using the new space on the
504device.
6f176b48 505
76a3a34d 506@item amend [-p] [-f @var{fmt}] [-t @var{cache}] -o @var{options} @var{filename}
6f176b48
HR
507
508Amends the image format specific @var{options} for the image file
509@var{filename}. Not all file formats support this operation.
acd935ef 510@end table
d3067b02 511@c man end
acd935ef 512
d3067b02
KW
513@ignore
514@c man begin NOTES
f932c040
KW
515Supported image file formats:
516
517@table @option
518@item raw
519
520Raw disk image format (default). This format has the advantage of
521being simple and easily exportable to all other emulators. If your
522file system supports @emph{holes} (for example in ext2 or ext3 on
523Linux or NTFS on Windows), then only the written sectors will reserve
524space. Use @code{qemu-img info} to know the real size used by the
525image or @code{ls -ls} on Unix/Linux.
526
06247428
HT
527Supported options:
528@table @code
529@item preallocation
530Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
531@code{falloc} mode preallocates space for image by calling posix_fallocate().
532@code{full} mode preallocates space for image by writing zeros to underlying
533storage.
534@end table
535
f932c040
KW
536@item qcow2
537QEMU image format, the most versatile format. Use it to have smaller
538images (useful if your filesystem does not supports holes, for example
539on Windows), optional AES encryption, zlib based compression and
540support of multiple VM snapshots.
8063d0fe 541
3e032364
KW
542Supported options:
543@table @code
d3067b02 544@item compat
7fa9e1f9
SH
545Determines the qcow2 version to use. @code{compat=0.10} uses the
546traditional image format that can be read by any QEMU since 0.10.
d3067b02 547@code{compat=1.1} enables image format extensions that only QEMU 1.1 and
7fa9e1f9
SH
548newer understand (this is the default). Amongst others, this includes zero
549clusters, which allow efficient copy-on-read for sparse images.
d3067b02 550
3e032364
KW
551@item backing_file
552File name of a base image (see @option{create} subcommand)
553@item backing_fmt
554Image format of the base image
555@item encryption
136cd19d 556If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC.
3e032364 557
136cd19d
DB
558The use of encryption in qcow and qcow2 images is considered to be flawed by
559modern cryptography standards, suffering from a number of design problems:
560
561@itemize @minus
562@item The AES-CBC cipher is used with predictable initialization vectors based
563on the sector number. This makes it vulnerable to chosen plaintext attacks
564which can reveal the existence of encrypted data.
565@item The user passphrase is directly used as the encryption key. A poorly
566chosen or short passphrase will compromise the security of the encryption.
567@item In the event of the passphrase being compromised there is no way to
568change the passphrase to protect data in any qcow images. The files must
569be cloned, using a different encryption passphrase in the new file. The
570original file must then be securely erased using a program like shred,
571though even this is ineffective with many modern storage technologies.
572@end itemize
573
574Use of qcow / qcow2 encryption is thus strongly discouraged. Users are
575recommended to use an alternative encryption technology such as the
576Linux dm-crypt / LUKS system.
3e032364
KW
577
578@item cluster_size
579Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
580sizes can improve the image file size whereas larger cluster sizes generally
581provide better performance.
582
583@item preallocation
0e4271b7
HT
584Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
585@code{full}). An image with preallocated metadata is initially larger but can
586improve performance when the image needs to grow. @code{falloc} and @code{full}
587preallocations are like the same options of @code{raw} format, but sets up
588metadata also.
3e032364 589
d3067b02
KW
590@item lazy_refcounts
591If this option is set to @code{on}, reference count updates are postponed with
592the goal of avoiding metadata I/O and improving performance. This is
593particularly interesting with @option{cache=writethrough} which doesn't batch
594metadata updates. The tradeoff is that after a host crash, the reference count
595tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
596check -r all} is required, which may take some time.
3e032364 597
d3067b02 598This option can only be enabled if @code{compat=1.1} is specified.
f085800e 599
4ab15590 600@item nocow
bc3a7f90 601If this option is set to @code{on}, it will turn off COW of the file. It's only
4ab15590
CL
602valid on btrfs, no effect on other file systems.
603
604Btrfs has low performance when hosting a VM image file, even more when the guest
605on the VM also using btrfs as file system. Turning off COW is a way to mitigate
606this bad performance. Generally there are two ways to turn off COW on btrfs:
607a) Disable it by mounting with nodatacow, then all newly created files will be
608NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
609does.
610
611Note: this option is only valid to new or empty files. If there is an existing
612file which is COW and has data blocks already, it couldn't be changed to NOCOW
613by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
bc3a7f90 614the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
4ab15590 615
f085800e 616@end table
3e032364 617
d3067b02
KW
618@item Other
619QEMU also supports various other image file formats for compatibility with
8282db1b
JC
620older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), VHDX,
621qcow1 and QED. For a full list of supported formats see @code{qemu-img --help}.
d3067b02
KW
622For a more detailed description of these formats, see the QEMU Emulation User
623Documentation.
3e032364 624
d3067b02
KW
625The main purpose of the block drivers for these formats is image conversion.
626For running VMs, it is recommended to convert the disk images to either raw or
627qcow2 in order to achieve good performance.
f932c040
KW
628@end table
629
630
acd935ef
FB
631@c man end
632
acd935ef
FB
633@setfilename qemu-img
634@settitle QEMU disk image utility
635
636@c man begin SEEALSO
637The HTML documentation of QEMU for more precise information and Linux
638user mode emulator invocation.
639@c man end
640
641@c man begin AUTHOR
642Fabrice Bellard
643@c man end
644
645@end ignore