blob: 8b05f2c42801a2535ab4390b47bc415eb880625a [file] [log] [blame]
bellardacd935e2004-11-15 22:57:26 +00001@example
2@c man begin SYNOPSIS
3usage: qemu-img command [command options]
4@c man end
5@end example
6
Kevin Wolf48467322012-08-16 10:56:35 +02007@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
bellardacd935e2004-11-15 22:57:26 +000017@c man begin OPTIONS
18
19The following commands are supported:
Stuart Brady153859b2009-06-07 00:42:17 +010020
21@include qemu-img-cmds.texi
bellardacd935e2004-11-15 22:57:26 +000022
23Command parameters:
24@table @var
25@item filename
26 is a disk image filename
ths5fafdf22007-09-16 21:08:06 +000027@item fmt
Kevin Wolff932c042009-10-28 12:49:15 +010028is the disk image format. It is guessed automatically in most cases. See below
29for a description of the supported disk formats.
bellardacd935e2004-11-15 22:57:26 +000030
ths5fafdf22007-09-16 21:08:06 +000031@item size
Kevin Wolfeff44262009-06-04 15:39:39 +020032is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
33(kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)
34and T (terabyte, 1024G) are supported. @code{b} is ignored.
bellardacd935e2004-11-15 22:57:26 +000035
36@item output_filename
ths5fafdf22007-09-16 21:08:06 +000037is the destination disk image filename
bellardacd935e2004-11-15 22:57:26 +000038
39@item output_fmt
40 is the destination format
Kevin Wolfeff44262009-06-04 15:39:39 +020041@item options
42is a comma separated list of format specific options in a
43name=value format. Use @code{-o ?} for an overview of the options supported
Kevin Wolf3e032362009-10-28 12:49:17 +010044by the used format or see the format descriptions below for details.
Kevin Wolfeff44262009-06-04 15:39:39 +020045
bellardacd935e2004-11-15 22:57:26 +000046
47@item -c
48indicates that target image must be compressed (qcow format only)
blueswir1d2c639d2009-01-24 18:19:25 +000049@item -h
50with or without a command shows help and lists the supported formats
Jes Sorensenaaf55b42011-07-19 15:01:34 +020051@item -p
52display progress bar (convert and rebase commands only)
Kevin Wolfa22f1232011-08-26 15:27:13 +020053@item -S @var{size}
54indicates the consecutive number of bytes that must contain only zeros
55for qemu-img to create a sparse image during conversion. This value is rounded
56down to the nearest 512 bytes. You may use the common size suffixes like
57@code{k} for kilobytes.
Kevin Wolf3763f262011-12-07 13:57:13 +010058@item -t @var{cache}
59specifies the cache mode that should be used with the (destination) file. See
60the documentation of the emulator's @code{-drive cache=...} option for allowed
61values.
blueswir1d2c639d2009-01-24 18:19:25 +000062@end table
63
64Parameters to snapshot subcommand:
65
66@table @option
67
68@item snapshot
69is the name of the snapshot to create, apply or delete
70@item -a
71applies a snapshot (revert disk to saved state)
72@item -c
73creates a snapshot
74@item -d
75deletes a snapshot
76@item -l
77lists all snapshots in the given image
bellardacd935e2004-11-15 22:57:26 +000078@end table
79
80Command description:
81
82@table @option
Kevin Wolf4534ff52012-05-11 16:07:02 +020083@item check [-f @var{fmt}] [-r [leaks | all]] @var{filename}
Kevin Wolfe6184692011-01-17 15:35:28 +010084
85Perform a consistency check on the disk image @var{filename}.
86
Kevin Wolf4534ff52012-05-11 16:07:02 +020087If @code{-r} is specified, qemu-img tries to repair any inconsistencies found
88during the check. @code{-r leaks} repairs only cluster leaks, whereas
89@code{-r all} fixes all kinds of errors, with a higher risk of choosing the
Stefan Weil0546b8c2012-08-10 22:03:25 +020090wrong fix or hiding corruption that has already occurred.
Kevin Wolf4534ff52012-05-11 16:07:02 +020091
Kevin Wolfe6184692011-01-17 15:35:28 +010092Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
93consistency checks.
94
Kevin Wolf8063d0f2009-10-28 12:49:16 +010095@item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
bellardacd935e2004-11-15 22:57:26 +000096
97Create the new disk image @var{filename} of size @var{size} and format
Kevin Wolf8063d0f2009-10-28 12:49:16 +010098@var{fmt}. Depending on the file format, you can add one or more @var{options}
99that enable additional features of this format.
bellardacd935e2004-11-15 22:57:26 +0000100
Kevin Wolf8063d0f2009-10-28 12:49:16 +0100101If the option @var{backing_file} is specified, then the image will record
102only the differences from @var{backing_file}. No size needs to be specified in
103this case. @var{backing_file} will never be modified unless you use the
104@code{commit} monitor command (or qemu-img commit).
bellardacd935e2004-11-15 22:57:26 +0000105
Kevin Wolfeff44262009-06-04 15:39:39 +0200106The size can also be specified using the @var{size} option with @code{-o},
107it doesn't need to be specified separately in this case.
108
Kevin Wolf3763f262011-12-07 13:57:13 +0100109@item commit [-f @var{fmt}] [-t @var{cache}] @var{filename}
bellardacd935e2004-11-15 22:57:26 +0000110
111Commit the changes recorded in @var{filename} in its base image.
112
Kevin Wolf3763f262011-12-07 13:57:13 +0100113@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}
bellardacd935e2004-11-15 22:57:26 +0000114
edison51ef6722010-09-21 19:58:41 -0700115Convert the disk image @var{filename} or a snapshot @var{snapshot_name} to disk image @var{output_filename}
Kevin Wolfeff44262009-06-04 15:39:39 +0200116using format @var{output_fmt}. It can be optionally compressed (@code{-c}
117option) or use any format specific options like encryption (@code{-o} option).
bellardacd935e2004-11-15 22:57:26 +0000118
Kevin Wolf8063d0f2009-10-28 12:49:16 +0100119Only the formats @code{qcow} and @code{qcow2} support compression. The
bellardacd935e2004-11-15 22:57:26 +0000120compression is read-only. It means that if a compressed sector is
121rewritten, then it is rewritten as uncompressed data.
122
bellardacd935e2004-11-15 22:57:26 +0000123Image conversion is also useful to get smaller image when using a
124growable format such as @code{qcow} or @code{cow}: the empty sectors
125are detected and suppressed from the destination image.
126
Kevin Wolf8063d0f2009-10-28 12:49:16 +0100127You can use the @var{backing_file} option to force the output image to be
128created as a copy on write image of the specified base image; the
129@var{backing_file} should have the same content as the input's base image,
130however the path, image format, etc may differ.
131
Benoît Canetc054b3f2012-09-05 13:09:02 +0200132@item info [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
bellardacd935e2004-11-15 22:57:26 +0000133
134Give information about the disk image @var{filename}. Use it in
135particular to know the size reserved on disk which can be different
bellard19d36792006-08-07 21:34:34 +0000136from the displayed size. If VM snapshots are stored in the disk image,
Benoît Canetc054b3f2012-09-05 13:09:02 +0200137they are displayed too. The command can output in the format @var{ofmt}
138which is either @code{human} or @code{json}.
blueswir1d2c639d2009-01-24 18:19:25 +0000139
140@item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
141
142List, apply, create or delete snapshots in image @var{filename}.
Stefan Hajnocziae6b0ed2010-04-24 09:12:12 +0100143
Kevin Wolf3763f262011-12-07 13:57:13 +0100144@item rebase [-f @var{fmt}] [-t @var{cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
Kevin Wolfe6184692011-01-17 15:35:28 +0100145
146Changes the backing file of an image. Only the formats @code{qcow2} and
147@code{qed} support changing the backing file.
148
149The backing file is changed to @var{backing_file} and (if the image format of
150@var{filename} supports this) the backing file format is changed to
151@var{backing_fmt}.
152
153There are two different modes in which @code{rebase} can operate:
154@table @option
155@item Safe mode
156This is the default mode and performs a real rebase operation. The new backing
157file may differ from the old one and qemu-img rebase will take care of keeping
158the guest-visible content of @var{filename} unchanged.
159
160In order to achieve this, any clusters that differ between @var{backing_file}
161and the old backing file of @var{filename} are merged into @var{filename}
162before actually changing the backing file.
163
164Note that the safe mode is an expensive operation, comparable to converting
165an image. It only works if the old backing file still exists.
166
167@item Unsafe mode
168qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the
169backing file name and format of @var{filename} is changed without any checks
170on the file contents. The user must take care of specifying the correct new
171backing file, or the guest-visible content of the image will be corrupted.
172
173This mode is useful for renaming or moving the backing file to somewhere else.
174It can be used without an accessible old backing file, i.e. you can use it to
175fix an image whose backing file has already been moved/renamed.
176@end table
177
Richard W.M. Jones9fda6ab2012-05-21 14:58:05 +0100178You can use @code{rebase} to perform a ``diff'' operation on two
179disk images. This can be useful when you have copied or cloned
180a guest, and you want to get back to a thin image on top of a
181template or base image.
182
183Say that @code{base.img} has been cloned as @code{modified.img} by
184copying it, and that the @code{modified.img} guest has run so there
185are now some changes compared to @code{base.img}. To construct a thin
186image called @code{diff.qcow2} that contains just the differences, do:
187
188@example
189qemu-img create -f qcow2 -b modified.img diff.qcow2
190qemu-img rebase -b base.img diff.qcow2
191@end example
192
193At this point, @code{modified.img} can be discarded, since
194@code{base.img + diff.qcow2} contains the same information.
195
Stefan Hajnocziae6b0ed2010-04-24 09:12:12 +0100196@item resize @var{filename} [+ | -]@var{size}
197
198Change the disk image as if it had been created with @var{size}.
199
200Before using this command to shrink a disk image, you MUST use file system and
201partitioning tools inside the VM to reduce allocated file systems and partition
202sizes accordingly. Failure to do so will result in data loss!
203
204After using this command to grow a disk image, you must use file system and
205partitioning tools inside the VM to actually begin using the new space on the
206device.
bellardacd935e2004-11-15 22:57:26 +0000207@end table
208
Kevin Wolff932c042009-10-28 12:49:15 +0100209Supported image file formats:
210
211@table @option
212@item raw
213
214Raw disk image format (default). This format has the advantage of
215being simple and easily exportable to all other emulators. If your
216file system supports @emph{holes} (for example in ext2 or ext3 on
217Linux or NTFS on Windows), then only the written sectors will reserve
218space. Use @code{qemu-img info} to know the real size used by the
219image or @code{ls -ls} on Unix/Linux.
220
Kevin Wolff932c042009-10-28 12:49:15 +0100221@item qcow2
222QEMU image format, the most versatile format. Use it to have smaller
223images (useful if your filesystem does not supports holes, for example
224on Windows), optional AES encryption, zlib based compression and
225support of multiple VM snapshots.
Kevin Wolf8063d0f2009-10-28 12:49:16 +0100226
Kevin Wolf3e032362009-10-28 12:49:17 +0100227Supported options:
228@table @code
229@item backing_file
230File name of a base image (see @option{create} subcommand)
231@item backing_fmt
232Image format of the base image
233@item encryption
234If this option is set to @code{on}, the image is encrypted.
235
Kevin Wolf8063d0f2009-10-28 12:49:16 +0100236Encryption uses the AES format which is very secure (128 bit keys). Use
237a long password (16 characters) to get maximum protection.
Kevin Wolf3e032362009-10-28 12:49:17 +0100238
239@item cluster_size
240Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
241sizes can improve the image file size whereas larger cluster sizes generally
242provide better performance.
243
244@item preallocation
245Preallocation mode (allowed values: off, metadata). An image with preallocated
246metadata is initially larger but can improve performance when the image needs
247to grow.
248
249@end table
250
Stefan Hajnoczif0858002012-06-13 14:29:15 +0100251@item qed
252Image format with support for backing files and compact image files (when your
253filesystem or transport medium does not support holes). Good performance due
254to less metadata than the more featureful qcow2 format, especially with
255cache=writethrough or cache=directsync. Consider using qcow2 which will soon
256have a similar optimization and is most actively developed.
257
258Supported options:
259@table @code
260@item backing_file
261File name of a base image (see @option{create} subcommand).
262@item backing_fmt
263Image file format of backing file (optional). Useful if the format cannot be
264autodetected because it has no header, like some vhd/vpc files.
265@item cluster_size
266Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
267cluster sizes can improve the image file size whereas larger cluster sizes
268generally provide better performance.
269@item table_size
270Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
271and 16). There is normally no need to change this value but this option can be
272used for performance benchmarking.
273@end table
Kevin Wolf3e032362009-10-28 12:49:17 +0100274
Kevin Wolff932c042009-10-28 12:49:15 +0100275@item qcow
276Old QEMU image format. Left for compatibility.
Kevin Wolf3e032362009-10-28 12:49:17 +0100277
278Supported options:
279@table @code
280@item backing_file
281File name of a base image (see @option{create} subcommand)
282@item encryption
283If this option is set to @code{on}, the image is encrypted.
284@end table
285
Kevin Wolff932c042009-10-28 12:49:15 +0100286@item cow
287User Mode Linux Copy On Write image format. Used to be the only growable
288image format in QEMU. It is supported only for compatibility with
289previous versions. It does not work on win32.
290@item vdi
291VirtualBox 1.1 compatible image format.
292@item vmdk
293VMware 3 and 4 compatible image format.
Kevin Wolf3e032362009-10-28 12:49:17 +0100294
295Supported options:
296@table @code
297@item backing_fmt
298Image format of the base image
299@item compat6
300Create a VMDK version 6 image (instead of version 4)
301@end table
302
303@item vpc
304VirtualPC compatible image format (VHD).
305
Kevin Wolff932c042009-10-28 12:49:15 +0100306@item cloop
307Linux Compressed Loop image, useful only to reuse directly compressed
308CD-ROM images present for example in the Knoppix CD-ROMs.
309@end table
310
311
bellardacd935e2004-11-15 22:57:26 +0000312@c man end
313
314@ignore
315
316@setfilename qemu-img
317@settitle QEMU disk image utility
318
319@c man begin SEEALSO
320The HTML documentation of QEMU for more precise information and Linux
321user mode emulator invocation.
322@c man end
323
324@c man begin AUTHOR
325Fabrice Bellard
326@c man end
327
328@end ignore