trap signals for "-serial mon:stdio"
[qemu.git] / qemu-img.texi
1 @example
2 @c man begin SYNOPSIS
3 usage: qemu-img command [command options]
4 @c man end
5 @end example
6
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.
10
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
16
17 @c man begin OPTIONS
18
19 The following commands are supported:
20
21 @include qemu-img-cmds.texi
22
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.
30
31 @item --backing-chain
32 will enumerate information about backing files in a disk image chain. Refer
33 below for further description.
34
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.
39
40 @item output_filename
41 is the destination disk image filename
42
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
50
51 @item -c
52 indicates that target image must be compressed (qcow format only)
53 @item -h
54 with or without a command shows help and lists the supported formats
55 @item -p
56 display progress bar (convert and rebase commands only)
57 @item -q
58 Quiet mode - do not print any output (except errors). There's no progress bar
59 in case both @var{-q} and @var{-p} options are used.
60 @item -S @var{size}
61 indicates the consecutive number of bytes that must contain only zeros
62 for qemu-img to create a sparse image during conversion. This value is rounded
63 down to the nearest 512 bytes. You may use the common size suffixes like
64 @code{k} for kilobytes.
65 @item -t @var{cache}
66 specifies the cache mode that should be used with the (destination) file. See
67 the documentation of the emulator's @code{-drive cache=...} option for allowed
68 values.
69 @end table
70
71 Parameters to snapshot subcommand:
72
73 @table @option
74
75 @item snapshot
76 is the name of the snapshot to create, apply or delete
77 @item -a
78 applies a snapshot (revert disk to saved state)
79 @item -c
80 creates a snapshot
81 @item -d
82 deletes a snapshot
83 @item -l
84 lists all snapshots in the given image
85 @end table
86
87 Parameters to compare subcommand:
88
89 @table @option
90
91 @item -f
92 First image format
93 @item -F
94 Second image format
95 @item -s
96 Strict mode - fail on on different image size or sector allocation
97 @end table
98
99 Command description:
100
101 @table @option
102 @item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] @var{filename}
103
104 Perform a consistency check on the disk image @var{filename}. The command can
105 output in the format @var{ofmt} which is either @code{human} or @code{json}.
106
107 If @code{-r} is specified, qemu-img tries to repair any inconsistencies found
108 during the check. @code{-r leaks} repairs only cluster leaks, whereas
109 @code{-r all} fixes all kinds of errors, with a higher risk of choosing the
110 wrong fix or hiding corruption that has already occurred.
111
112 Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
113 consistency checks.
114
115 @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
116
117 Create the new disk image @var{filename} of size @var{size} and format
118 @var{fmt}. Depending on the file format, you can add one or more @var{options}
119 that enable additional features of this format.
120
121 If the option @var{backing_file} is specified, then the image will record
122 only the differences from @var{backing_file}. No size needs to be specified in
123 this case. @var{backing_file} will never be modified unless you use the
124 @code{commit} monitor command (or qemu-img commit).
125
126 The size can also be specified using the @var{size} option with @code{-o},
127 it doesn't need to be specified separately in this case.
128
129 @item commit [-f @var{fmt}] [-t @var{cache}] @var{filename}
130
131 Commit the changes recorded in @var{filename} in its base image.
132
133 @item compare [-f @var{fmt}] [-F @var{fmt}] [-p] [-s] [-q] @var{filename1} @var{filename2}
134
135 Check if two images have the same content. You can compare images with
136 different format or settings.
137
138 The format is probed unless you specify it by @var{-f} (used for
139 @var{filename1}) and/or @var{-F} (used for @var{filename2}) option.
140
141 By default, images with different size are considered identical if the larger
142 image contains only unallocated and/or zeroed sectors in the area after the end
143 of the other image. In addition, if any sector is not allocated in one image
144 and contains only zero bytes in the second one, it is evaluated as equal. You
145 can use Strict mode by specifying the @var{-s} option. When compare runs in
146 Strict mode, it fails in case image size differs or a sector is allocated in
147 one image and is not allocated in the second one.
148
149 By default, compare prints out a result message. This message displays
150 information that both images are same or the position of the first different
151 byte. In addition, result message can report different image size in case
152 Strict mode is used.
153
154 Compare exits with @code{0} in case the images are equal and with @code{1}
155 in case the images differ. Other exit codes mean an error occurred during
156 execution and standard error output should contain an error message.
157 The following table sumarizes all exit codes of the compare subcommand:
158
159 @table @option
160
161 @item 0
162 Images are identical
163 @item 1
164 Images differ
165 @item 2
166 Error on opening an image
167 @item 3
168 Error on checking a sector allocation
169 @item 4
170 Error on reading data
171
172 @end table
173
174 @item convert [-c] [-p] [-f @var{fmt}] [-t @var{cache}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_name}] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename}
175
176 Convert the disk image @var{filename} or a snapshot @var{snapshot_name} to disk image @var{output_filename}
177 using format @var{output_fmt}. It can be optionally compressed (@code{-c}
178 option) or use any format specific options like encryption (@code{-o} option).
179
180 Only the formats @code{qcow} and @code{qcow2} support compression. The
181 compression is read-only. It means that if a compressed sector is
182 rewritten, then it is rewritten as uncompressed data.
183
184 Image conversion is also useful to get smaller image when using a
185 growable format such as @code{qcow} or @code{cow}: the empty sectors
186 are detected and suppressed from the destination image.
187
188 You can use the @var{backing_file} option to force the output image to be
189 created as a copy on write image of the specified base image; the
190 @var{backing_file} should have the same content as the input's base image,
191 however the path, image format, etc may differ.
192
193 @item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename}
194
195 Give information about the disk image @var{filename}. Use it in
196 particular to know the size reserved on disk which can be different
197 from the displayed size. If VM snapshots are stored in the disk image,
198 they are displayed too. The command can output in the format @var{ofmt}
199 which is either @code{human} or @code{json}.
200
201 If a disk image has a backing file chain, information about each disk image in
202 the chain can be recursively enumerated by using the option @code{--backing-chain}.
203
204 For instance, if you have an image chain like:
205
206 @example
207 base.qcow2 <- snap1.qcow2 <- snap2.qcow2
208 @end example
209
210 To enumerate information about each disk image in the above chain, starting from top to base, do:
211
212 @example
213 qemu-img info --backing-chain snap2.qcow2
214 @end example
215
216 @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
217
218 List, apply, create or delete snapshots in image @var{filename}.
219
220 @item rebase [-f @var{fmt}] [-t @var{cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
221
222 Changes the backing file of an image. Only the formats @code{qcow2} and
223 @code{qed} support changing the backing file.
224
225 The backing file is changed to @var{backing_file} and (if the image format of
226 @var{filename} supports this) the backing file format is changed to
227 @var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty
228 string), then the image is rebased onto no backing file (i.e. it will exist
229 independently of any backing file).
230
231 There are two different modes in which @code{rebase} can operate:
232 @table @option
233 @item Safe mode
234 This is the default mode and performs a real rebase operation. The new backing
235 file may differ from the old one and qemu-img rebase will take care of keeping
236 the guest-visible content of @var{filename} unchanged.
237
238 In order to achieve this, any clusters that differ between @var{backing_file}
239 and the old backing file of @var{filename} are merged into @var{filename}
240 before actually changing the backing file.
241
242 Note that the safe mode is an expensive operation, comparable to converting
243 an image. It only works if the old backing file still exists.
244
245 @item Unsafe mode
246 qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the
247 backing file name and format of @var{filename} is changed without any checks
248 on the file contents. The user must take care of specifying the correct new
249 backing file, or the guest-visible content of the image will be corrupted.
250
251 This mode is useful for renaming or moving the backing file to somewhere else.
252 It can be used without an accessible old backing file, i.e. you can use it to
253 fix an image whose backing file has already been moved/renamed.
254 @end table
255
256 You can use @code{rebase} to perform a ``diff'' operation on two
257 disk images.  This can be useful when you have copied or cloned
258 a guest, and you want to get back to a thin image on top of a
259 template or base image.
260
261 Say that @code{base.img} has been cloned as @code{modified.img} by
262 copying it, and that the @code{modified.img} guest has run so there
263 are now some changes compared to @code{base.img}.  To construct a thin
264 image called @code{diff.qcow2} that contains just the differences, do:
265
266 @example
267 qemu-img create -f qcow2 -b modified.img diff.qcow2
268 qemu-img rebase -b base.img diff.qcow2
269 @end example
270
271 At this point, @code{modified.img} can be discarded, since
272 @code{base.img + diff.qcow2} contains the same information.
273
274 @item resize @var{filename} [+ | -]@var{size}
275
276 Change the disk image as if it had been created with @var{size}.
277
278 Before using this command to shrink a disk image, you MUST use file system and
279 partitioning tools inside the VM to reduce allocated file systems and partition
280 sizes accordingly.  Failure to do so will result in data loss!
281
282 After using this command to grow a disk image, you must use file system and
283 partitioning tools inside the VM to actually begin using the new space on the
284 device.
285 @end table
286 @c man end
287
288 @ignore
289 @c man begin NOTES
290 Supported image file formats:
291
292 @table @option
293 @item raw
294
295 Raw disk image format (default). This format has the advantage of
296 being simple and easily exportable to all other emulators. If your
297 file system supports @emph{holes} (for example in ext2 or ext3 on
298 Linux or NTFS on Windows), then only the written sectors will reserve
299 space. Use @code{qemu-img info} to know the real size used by the
300 image or @code{ls -ls} on Unix/Linux.
301
302 @item qcow2
303 QEMU image format, the most versatile format. Use it to have smaller
304 images (useful if your filesystem does not supports holes, for example
305 on Windows), optional AES encryption, zlib based compression and
306 support of multiple VM snapshots.
307
308 Supported options:
309 @table @code
310 @item compat
311 Determines the qcow2 version to use. @code{compat=0.10} uses the traditional
312 image format that can be read by any QEMU since 0.10 (this is the default).
313 @code{compat=1.1} enables image format extensions that only QEMU 1.1 and
314 newer understand. Amongst others, this includes zero clusters, which allow
315 efficient copy-on-read for sparse images.
316
317 @item backing_file
318 File name of a base image (see @option{create} subcommand)
319 @item backing_fmt
320 Image format of the base image
321 @item encryption
322 If this option is set to @code{on}, the image is encrypted.
323
324 Encryption uses the AES format which is very secure (128 bit keys). Use
325 a long password (16 characters) to get maximum protection.
326
327 @item cluster_size
328 Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
329 sizes can improve the image file size whereas larger cluster sizes generally
330 provide better performance.
331
332 @item preallocation
333 Preallocation mode (allowed values: off, metadata). An image with preallocated
334 metadata is initially larger but can improve performance when the image needs
335 to grow.
336
337 @item lazy_refcounts
338 If this option is set to @code{on}, reference count updates are postponed with
339 the goal of avoiding metadata I/O and improving performance. This is
340 particularly interesting with @option{cache=writethrough} which doesn't batch
341 metadata updates. The tradeoff is that after a host crash, the reference count
342 tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
343 check -r all} is required, which may take some time.
344
345 This option can only be enabled if @code{compat=1.1} is specified.
346
347 @end table
348
349 @item Other
350 QEMU also supports various other image file formats for compatibility with
351 older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), qcow1
352 and QED. For a full list of supported formats see @code{qemu-img --help}.
353 For a more detailed description of these formats, see the QEMU Emulation User
354 Documentation.
355
356 The main purpose of the block drivers for these formats is image conversion.
357 For running VMs, it is recommended to convert the disk images to either raw or
358 qcow2 in order to achieve good performance.
359 @end table
360
361
362 @c man end
363
364 @setfilename qemu-img
365 @settitle QEMU disk image utility
366
367 @c man begin SEEALSO
368 The HTML documentation of QEMU for more precise information and Linux
369 user mode emulator invocation.
370 @c man end
371
372 @c man begin AUTHOR
373 Fabrice Bellard
374 @c man end
375
376 @end ignore