char/cadence_uart: Fix can_receive logic
[qemu.git] / qemu-img.texi
blobbe31191e43413f88fc3ff23d613cbb70221bb218
1 @example
2 @c man begin SYNOPSIS
3 usage: qemu-img command [command options]
4 @c man end
5 @end example
7 @c man begin DESCRIPTION
8 qemu-img allows you to create, convert and modify images offline. It can handle
9 all image formats supported by QEMU.
11 @b{Warning:} Never use qemu-img to modify images in use by a running virtual
12 machine or any other process; this may destroy the image. Also, be aware that
13 querying an image that is being modified by another process may encounter
14 inconsistent state.
15 @c man end
17 @c man begin OPTIONS
19 The following commands are supported:
21 @include qemu-img-cmds.texi
23 Command parameters:
24 @table @var
25 @item filename
26  is a disk image filename
27 @item fmt
28 is the disk image format. It is guessed automatically in most cases. See below
29 for a description of the supported disk formats.
31 @item --backing-chain
32 will enumerate information about backing files in a disk image chain. Refer
33 below for further description.
35 @item size
36 is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
37 (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)
38 and T (terabyte, 1024G) are supported.  @code{b} is ignored.
40 @item output_filename
41 is the destination disk image filename
43 @item output_fmt
44  is the destination format
45 @item options
46 is a comma separated list of format specific options in a
47 name=value format. Use @code{-o ?} for an overview of the options supported
48 by the used format or see the format descriptions below for details.
49 @item snapshot_param
50 is param used for internal snapshot, format is
51 'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'
52 @item snapshot_id_or_name
53 is deprecated, use snapshot_param instead
55 @item -c
56 indicates that target image must be compressed (qcow format only)
57 @item -h
58 with or without a command shows help and lists the supported formats
59 @item -p
60 display progress bar (convert and rebase commands only)
61 @item -q
62 Quiet mode - do not print any output (except errors). There's no progress bar
63 in case both @var{-q} and @var{-p} options are used.
64 @item -S @var{size}
65 indicates the consecutive number of bytes that must contain only zeros
66 for qemu-img to create a sparse image during conversion. This value is rounded
67 down to the nearest 512 bytes. You may use the common size suffixes like
68 @code{k} for kilobytes.
69 @item -t @var{cache}
70 specifies the cache mode that should be used with the (destination) file. See
71 the documentation of the emulator's @code{-drive cache=...} option for allowed
72 values.
73 @end table
75 Parameters to snapshot subcommand:
77 @table @option
79 @item snapshot
80 is the name of the snapshot to create, apply or delete
81 @item -a
82 applies a snapshot (revert disk to saved state)
83 @item -c
84 creates a snapshot
85 @item -d
86 deletes a snapshot
87 @item -l
88 lists all snapshots in the given image
89 @end table
91 Parameters to compare subcommand:
93 @table @option
95 @item -f
96 First image format
97 @item -F
98 Second image format
99 @item -s
100 Strict mode - fail on on different image size or sector allocation
101 @end table
103 Parameters to convert subcommand:
105 @table @option
107 @item -n
108 Skip the creation of the target volume
109 @end table
111 Command description:
113 @table @option
114 @item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] @var{filename}
116 Perform a consistency check on the disk image @var{filename}. The command can
117 output in the format @var{ofmt} which is either @code{human} or @code{json}.
119 If @code{-r} is specified, qemu-img tries to repair any inconsistencies found
120 during the check. @code{-r leaks} repairs only cluster leaks, whereas
121 @code{-r all} fixes all kinds of errors, with a higher risk of choosing the
122 wrong fix or hiding corruption that has already occurred.
124 Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
125 consistency checks.
127 @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
129 Create the new disk image @var{filename} of size @var{size} and format
130 @var{fmt}. Depending on the file format, you can add one or more @var{options}
131 that enable additional features of this format.
133 If the option @var{backing_file} is specified, then the image will record
134 only the differences from @var{backing_file}. No size needs to be specified in
135 this case. @var{backing_file} will never be modified unless you use the
136 @code{commit} monitor command (or qemu-img commit).
138 The size can also be specified using the @var{size} option with @code{-o},
139 it doesn't need to be specified separately in this case.
141 @item commit [-f @var{fmt}] [-t @var{cache}] @var{filename}
143 Commit the changes recorded in @var{filename} in its base image.
145 @item compare [-f @var{fmt}] [-F @var{fmt}] [-p] [-s] [-q] @var{filename1} @var{filename2}
147 Check if two images have the same content. You can compare images with
148 different format or settings.
150 The format is probed unless you specify it by @var{-f} (used for
151 @var{filename1}) and/or @var{-F} (used for @var{filename2}) option.
153 By default, images with different size are considered identical if the larger
154 image contains only unallocated and/or zeroed sectors in the area after the end
155 of the other image. In addition, if any sector is not allocated in one image
156 and contains only zero bytes in the second one, it is evaluated as equal. You
157 can use Strict mode by specifying the @var{-s} option. When compare runs in
158 Strict mode, it fails in case image size differs or a sector is allocated in
159 one image and is not allocated in the second one.
161 By default, compare prints out a result message. This message displays
162 information that both images are same or the position of the first different
163 byte. In addition, result message can report different image size in case
164 Strict mode is used.
166 Compare exits with @code{0} in case the images are equal and with @code{1}
167 in case the images differ. Other exit codes mean an error occurred during
168 execution and standard error output should contain an error message.
169 The following table sumarizes all exit codes of the compare subcommand:
171 @table @option
173 @item 0
174 Images are identical
175 @item 1
176 Images differ
177 @item 2
178 Error on opening an image
179 @item 3
180 Error on checking a sector allocation
181 @item 4
182 Error on reading data
184 @end table
186 @item convert [-c] [-p] [-n] [-f @var{fmt}] [-t @var{cache}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_id_or_name}] [-l @var{snapshot_param}] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename}
188 Convert the disk image @var{filename} or a snapshot @var{snapshot_param}(@var{snapshot_id_or_name} is deprecated)
189 to disk image @var{output_filename} using format @var{output_fmt}. It can be optionally compressed (@code{-c}
190 option) or use any format specific options like encryption (@code{-o} option).
192 Only the formats @code{qcow} and @code{qcow2} support compression. The
193 compression is read-only. It means that if a compressed sector is
194 rewritten, then it is rewritten as uncompressed data.
196 Image conversion is also useful to get smaller image when using a
197 growable format such as @code{qcow} or @code{cow}: the empty sectors
198 are detected and suppressed from the destination image.
200 @var{sparse_size} indicates the consecutive number of bytes (defaults to 4k)
201 that must contain only zeros for qemu-img to create a sparse image during
202 conversion. If @var{sparse_size} is 0, the source will not be scanned for
203 unallocated or zero sectors, and the destination image will always be
204 fully allocated.
206 You can use the @var{backing_file} option to force the output image to be
207 created as a copy on write image of the specified base image; the
208 @var{backing_file} should have the same content as the input's base image,
209 however the path, image format, etc may differ.
211 If the @code{-n} option is specified, the target volume creation will be
212 skipped. This is useful for formats such as @code{rbd} if the target
213 volume has already been created with site specific options that cannot
214 be supplied through qemu-img.
216 @item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename}
218 Give information about the disk image @var{filename}. Use it in
219 particular to know the size reserved on disk which can be different
220 from the displayed size. If VM snapshots are stored in the disk image,
221 they are displayed too. The command can output in the format @var{ofmt}
222 which is either @code{human} or @code{json}.
224 If a disk image has a backing file chain, information about each disk image in
225 the chain can be recursively enumerated by using the option @code{--backing-chain}.
227 For instance, if you have an image chain like:
229 @example
230 base.qcow2 <- snap1.qcow2 <- snap2.qcow2
231 @end example
233 To enumerate information about each disk image in the above chain, starting from top to base, do:
235 @example
236 qemu-img info --backing-chain snap2.qcow2
237 @end example
239 @item map [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
241 Dump the metadata of image @var{filename} and its backing file chain.
242 In particular, this commands dumps the allocation state of every sector
243 of @var{filename}, together with the topmost file that allocates it in
244 the backing file chain.
246 Two option formats are possible.  The default format (@code{human})
247 only dumps known-nonzero areas of the file.  Known-zero parts of the
248 file are omitted altogether, and likewise for parts that are not allocated
249 throughout the chain.  @command{qemu-img} output will identify a file
250 from where the data can be read, and the offset in the file.  Each line
251 will include four fields, the first three of which are hexadecimal
252 numbers.  For example the first line of:
253 @example
254 Offset          Length          Mapped to       File
255 0               0x20000         0x50000         /tmp/overlay.qcow2
256 0x100000        0x10000         0x95380000      /tmp/backing.qcow2
257 @end example
258 @noindent
259 means that 0x20000 (131072) bytes starting at offset 0 in the image are
260 available in /tmp/overlay.qcow2 (opened in @code{raw} format) starting
261 at offset 0x50000 (327680).  Data that is compressed, encrypted, or
262 otherwise not available in raw format will cause an error if @code{human}
263 format is in use.  Note that file names can include newlines, thus it is
264 not safe to parse this output format in scripts.
266 The alternative format @code{json} will return an array of dictionaries
267 in JSON format.  It will include similar information in
268 the @code{start}, @code{length}, @code{offset} fields;
269 it will also include other more specific information:
270 @itemize @minus
271 @item
272 whether the sectors contain actual data or not (boolean field @code{data};
273 if false, the sectors are either unallocated or stored as optimized
274 all-zero clusters);
276 @item
277 whether the data is known to read as zero (boolean field @code{zero});
279 @item
280 in order to make the output shorter, the target file is expressed as
281 a @code{depth}; for example, a depth of 2 refers to the backing file
282 of the backing file of @var{filename}.
283 @end itemize
285 In JSON format, the @code{offset} field is optional; it is absent in
286 cases where @code{human} format would omit the entry or exit with an error.
287 If @code{data} is false and the @code{offset} field is present, the
288 corresponding sectors in the file are not yet in use, but they are
289 preallocated.
291 For more information, consult @file{include/block/block.h} in QEMU's
292 source code.
294 @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
296 List, apply, create or delete snapshots in image @var{filename}.
298 @item rebase [-f @var{fmt}] [-t @var{cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
300 Changes the backing file of an image. Only the formats @code{qcow2} and
301 @code{qed} support changing the backing file.
303 The backing file is changed to @var{backing_file} and (if the image format of
304 @var{filename} supports this) the backing file format is changed to
305 @var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty
306 string), then the image is rebased onto no backing file (i.e. it will exist
307 independently of any backing file).
309 There are two different modes in which @code{rebase} can operate:
310 @table @option
311 @item Safe mode
312 This is the default mode and performs a real rebase operation. The new backing
313 file may differ from the old one and qemu-img rebase will take care of keeping
314 the guest-visible content of @var{filename} unchanged.
316 In order to achieve this, any clusters that differ between @var{backing_file}
317 and the old backing file of @var{filename} are merged into @var{filename}
318 before actually changing the backing file.
320 Note that the safe mode is an expensive operation, comparable to converting
321 an image. It only works if the old backing file still exists.
323 @item Unsafe mode
324 qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the
325 backing file name and format of @var{filename} is changed without any checks
326 on the file contents. The user must take care of specifying the correct new
327 backing file, or the guest-visible content of the image will be corrupted.
329 This mode is useful for renaming or moving the backing file to somewhere else.
330 It can be used without an accessible old backing file, i.e. you can use it to
331 fix an image whose backing file has already been moved/renamed.
332 @end table
334 You can use @code{rebase} to perform a ``diff'' operation on two
335 disk images.  This can be useful when you have copied or cloned
336 a guest, and you want to get back to a thin image on top of a
337 template or base image.
339 Say that @code{base.img} has been cloned as @code{modified.img} by
340 copying it, and that the @code{modified.img} guest has run so there
341 are now some changes compared to @code{base.img}.  To construct a thin
342 image called @code{diff.qcow2} that contains just the differences, do:
344 @example
345 qemu-img create -f qcow2 -b modified.img diff.qcow2
346 qemu-img rebase -b base.img diff.qcow2
347 @end example
349 At this point, @code{modified.img} can be discarded, since
350 @code{base.img + diff.qcow2} contains the same information.
352 @item resize @var{filename} [+ | -]@var{size}
354 Change the disk image as if it had been created with @var{size}.
356 Before using this command to shrink a disk image, you MUST use file system and
357 partitioning tools inside the VM to reduce allocated file systems and partition
358 sizes accordingly.  Failure to do so will result in data loss!
360 After using this command to grow a disk image, you must use file system and
361 partitioning tools inside the VM to actually begin using the new space on the
362 device.
364 @item amend [-f @var{fmt}] -o @var{options} @var{filename}
366 Amends the image format specific @var{options} for the image file
367 @var{filename}. Not all file formats support this operation.
368 @end table
369 @c man end
371 @ignore
372 @c man begin NOTES
373 Supported image file formats:
375 @table @option
376 @item raw
378 Raw disk image format (default). This format has the advantage of
379 being simple and easily exportable to all other emulators. If your
380 file system supports @emph{holes} (for example in ext2 or ext3 on
381 Linux or NTFS on Windows), then only the written sectors will reserve
382 space. Use @code{qemu-img info} to know the real size used by the
383 image or @code{ls -ls} on Unix/Linux.
385 @item qcow2
386 QEMU image format, the most versatile format. Use it to have smaller
387 images (useful if your filesystem does not supports holes, for example
388 on Windows), optional AES encryption, zlib based compression and
389 support of multiple VM snapshots.
391 Supported options:
392 @table @code
393 @item compat
394 Determines the qcow2 version to use. @code{compat=0.10} uses the traditional
395 image format that can be read by any QEMU since 0.10 (this is the default).
396 @code{compat=1.1} enables image format extensions that only QEMU 1.1 and
397 newer understand. Amongst others, this includes zero clusters, which allow
398 efficient copy-on-read for sparse images.
400 @item backing_file
401 File name of a base image (see @option{create} subcommand)
402 @item backing_fmt
403 Image format of the base image
404 @item encryption
405 If this option is set to @code{on}, the image is encrypted.
407 Encryption uses the AES format which is very secure (128 bit keys). Use
408 a long password (16 characters) to get maximum protection.
410 @item cluster_size
411 Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
412 sizes can improve the image file size whereas larger cluster sizes generally
413 provide better performance.
415 @item preallocation
416 Preallocation mode (allowed values: off, metadata). An image with preallocated
417 metadata is initially larger but can improve performance when the image needs
418 to grow.
420 @item lazy_refcounts
421 If this option is set to @code{on}, reference count updates are postponed with
422 the goal of avoiding metadata I/O and improving performance. This is
423 particularly interesting with @option{cache=writethrough} which doesn't batch
424 metadata updates. The tradeoff is that after a host crash, the reference count
425 tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
426 check -r all} is required, which may take some time.
428 This option can only be enabled if @code{compat=1.1} is specified.
430 @end table
432 @item Other
433 QEMU also supports various other image file formats for compatibility with
434 older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), qcow1
435 and QED. For a full list of supported formats see @code{qemu-img --help}.
436 For a more detailed description of these formats, see the QEMU Emulation User
437 Documentation.
439 The main purpose of the block drivers for these formats is image conversion.
440 For running VMs, it is recommended to convert the disk images to either raw or
441 qcow2 in order to achieve good performance.
442 @end table
445 @c man end
447 @setfilename qemu-img
448 @settitle QEMU disk image utility
450 @c man begin SEEALSO
451 The HTML documentation of QEMU for more precise information and Linux
452 user mode emulator invocation.
453 @c man end
455 @c man begin AUTHOR
456 Fabrice Bellard
457 @c man end
459 @end ignore