Merge branch 'upstream-merge'
[qemu-kvm.git] / qemu-img.texi
blob8b05f2c42801a2535ab4390b47bc415eb880625a
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 size
32 is 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)
34 and T (terabyte, 1024G) are supported.  @code{b} is ignored.
36 @item output_filename
37 is the destination disk image filename
39 @item output_fmt
40  is the destination format
41 @item options
42 is a comma separated list of format specific options in a
43 name=value format. Use @code{-o ?} for an overview of the options supported
44 by the used format or see the format descriptions below for details.
47 @item -c
48 indicates that target image must be compressed (qcow format only)
49 @item -h
50 with or without a command shows help and lists the supported formats
51 @item -p
52 display progress bar (convert and rebase commands only)
53 @item -S @var{size}
54 indicates the consecutive number of bytes that must contain only zeros
55 for qemu-img to create a sparse image during conversion. This value is rounded
56 down to the nearest 512 bytes. You may use the common size suffixes like
57 @code{k} for kilobytes.
58 @item -t @var{cache}
59 specifies the cache mode that should be used with the (destination) file. See
60 the documentation of the emulator's @code{-drive cache=...} option for allowed
61 values.
62 @end table
64 Parameters to snapshot subcommand:
66 @table @option
68 @item snapshot
69 is the name of the snapshot to create, apply or delete
70 @item -a
71 applies a snapshot (revert disk to saved state)
72 @item -c
73 creates a snapshot
74 @item -d
75 deletes a snapshot
76 @item -l
77 lists all snapshots in the given image
78 @end table
80 Command description:
82 @table @option
83 @item check [-f @var{fmt}] [-r [leaks | all]] @var{filename}
85 Perform a consistency check on the disk image @var{filename}.
87 If @code{-r} is specified, qemu-img tries to repair any inconsistencies found
88 during 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
90 wrong fix or hiding corruption that has already occurred.
92 Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
93 consistency checks.
95 @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
97 Create the new disk image @var{filename} of size @var{size} and format
98 @var{fmt}. Depending on the file format, you can add one or more @var{options}
99 that enable additional features of this format.
101 If the option @var{backing_file} is specified, then the image will record
102 only the differences from @var{backing_file}. No size needs to be specified in
103 this case. @var{backing_file} will never be modified unless you use the
104 @code{commit} monitor command (or qemu-img commit).
106 The size can also be specified using the @var{size} option with @code{-o},
107 it doesn't need to be specified separately in this case.
109 @item commit [-f @var{fmt}] [-t @var{cache}] @var{filename}
111 Commit the changes recorded in @var{filename} in its base image.
113 @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}
115 Convert the disk image @var{filename} or a snapshot @var{snapshot_name} to disk image @var{output_filename}
116 using format @var{output_fmt}. It can be optionally compressed (@code{-c}
117 option) or use any format specific options like encryption (@code{-o} option).
119 Only the formats @code{qcow} and @code{qcow2} support compression. The
120 compression is read-only. It means that if a compressed sector is
121 rewritten, then it is rewritten as uncompressed data.
123 Image conversion is also useful to get smaller image when using a
124 growable format such as @code{qcow} or @code{cow}: the empty sectors
125 are detected and suppressed from the destination image.
127 You can use the @var{backing_file} option to force the output image to be
128 created 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,
130 however the path, image format, etc may differ.
132 @item info [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
134 Give information about the disk image @var{filename}. Use it in
135 particular to know the size reserved on disk which can be different
136 from the displayed size. If VM snapshots are stored in the disk image,
137 they are displayed too. The command can output in the format @var{ofmt}
138 which is either @code{human} or @code{json}.
140 @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
142 List, apply, create or delete snapshots in image @var{filename}.
144 @item rebase [-f @var{fmt}] [-t @var{cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
146 Changes the backing file of an image. Only the formats @code{qcow2} and
147 @code{qed} support changing the backing file.
149 The 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}.
153 There are two different modes in which @code{rebase} can operate:
154 @table @option
155 @item Safe mode
156 This is the default mode and performs a real rebase operation. The new backing
157 file may differ from the old one and qemu-img rebase will take care of keeping
158 the guest-visible content of @var{filename} unchanged.
160 In order to achieve this, any clusters that differ between @var{backing_file}
161 and the old backing file of @var{filename} are merged into @var{filename}
162 before actually changing the backing file.
164 Note that the safe mode is an expensive operation, comparable to converting
165 an image. It only works if the old backing file still exists.
167 @item Unsafe mode
168 qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the
169 backing file name and format of @var{filename} is changed without any checks
170 on the file contents. The user must take care of specifying the correct new
171 backing file, or the guest-visible content of the image will be corrupted.
173 This mode is useful for renaming or moving the backing file to somewhere else.
174 It can be used without an accessible old backing file, i.e. you can use it to
175 fix an image whose backing file has already been moved/renamed.
176 @end table
178 You can use @code{rebase} to perform a ``diff'' operation on two
179 disk images.  This can be useful when you have copied or cloned
180 a guest, and you want to get back to a thin image on top of a
181 template or base image.
183 Say that @code{base.img} has been cloned as @code{modified.img} by
184 copying it, and that the @code{modified.img} guest has run so there
185 are now some changes compared to @code{base.img}.  To construct a thin
186 image called @code{diff.qcow2} that contains just the differences, do:
188 @example
189 qemu-img create -f qcow2 -b modified.img diff.qcow2
190 qemu-img rebase -b base.img diff.qcow2
191 @end example
193 At this point, @code{modified.img} can be discarded, since
194 @code{base.img + diff.qcow2} contains the same information.
196 @item resize @var{filename} [+ | -]@var{size}
198 Change the disk image as if it had been created with @var{size}.
200 Before using this command to shrink a disk image, you MUST use file system and
201 partitioning tools inside the VM to reduce allocated file systems and partition
202 sizes accordingly.  Failure to do so will result in data loss!
204 After using this command to grow a disk image, you must use file system and
205 partitioning tools inside the VM to actually begin using the new space on the
206 device.
207 @end table
209 Supported image file formats:
211 @table @option
212 @item raw
214 Raw disk image format (default). This format has the advantage of
215 being simple and easily exportable to all other emulators. If your
216 file system supports @emph{holes} (for example in ext2 or ext3 on
217 Linux or NTFS on Windows), then only the written sectors will reserve
218 space. Use @code{qemu-img info} to know the real size used by the
219 image or @code{ls -ls} on Unix/Linux.
221 @item qcow2
222 QEMU image format, the most versatile format. Use it to have smaller
223 images (useful if your filesystem does not supports holes, for example
224 on Windows), optional AES encryption, zlib based compression and
225 support of multiple VM snapshots.
227 Supported options:
228 @table @code
229 @item backing_file
230 File name of a base image (see @option{create} subcommand)
231 @item backing_fmt
232 Image format of the base image
233 @item encryption
234 If this option is set to @code{on}, the image is encrypted.
236 Encryption uses the AES format which is very secure (128 bit keys). Use
237 a long password (16 characters) to get maximum protection.
239 @item cluster_size
240 Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
241 sizes can improve the image file size whereas larger cluster sizes generally
242 provide better performance.
244 @item preallocation
245 Preallocation mode (allowed values: off, metadata). An image with preallocated
246 metadata is initially larger but can improve performance when the image needs
247 to grow.
249 @end table
251 @item qed
252 Image format with support for backing files and compact image files (when your
253 filesystem or transport medium does not support holes).  Good performance due
254 to less metadata than the more featureful qcow2 format, especially with
255 cache=writethrough or cache=directsync.  Consider using qcow2 which will soon
256 have a similar optimization and is most actively developed.
258 Supported options:
259 @table @code
260 @item backing_file
261 File name of a base image (see @option{create} subcommand).
262 @item backing_fmt
263 Image file format of backing file (optional).  Useful if the format cannot be
264 autodetected because it has no header, like some vhd/vpc files.
265 @item cluster_size
266 Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
267 cluster sizes can improve the image file size whereas larger cluster sizes
268 generally provide better performance.
269 @item table_size
270 Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
271 and 16).  There is normally no need to change this value but this option can be
272 used for performance benchmarking.
273 @end table
275 @item qcow
276 Old QEMU image format. Left for compatibility.
278 Supported options:
279 @table @code
280 @item backing_file
281 File name of a base image (see @option{create} subcommand)
282 @item encryption
283 If this option is set to @code{on}, the image is encrypted.
284 @end table
286 @item cow
287 User Mode Linux Copy On Write image format. Used to be the only growable
288 image format in QEMU. It is supported only for compatibility with
289 previous versions. It does not work on win32.
290 @item vdi
291 VirtualBox 1.1 compatible image format.
292 @item vmdk
293 VMware 3 and 4 compatible image format.
295 Supported options:
296 @table @code
297 @item backing_fmt
298 Image format of the base image
299 @item compat6
300 Create a VMDK version 6 image (instead of version 4)
301 @end table
303 @item vpc
304 VirtualPC compatible image format (VHD).
306 @item cloop
307 Linux Compressed Loop image, useful only to reuse directly compressed
308 CD-ROM images present for example in the Knoppix CD-ROMs.
309 @end table
312 @c man end
314 @ignore
316 @setfilename qemu-img
317 @settitle QEMU disk image utility
319 @c man begin SEEALSO
320 The HTML documentation of QEMU for more precise information and Linux
321 user mode emulator invocation.
322 @c man end
324 @c man begin AUTHOR
325 Fabrice Bellard
326 @c man end
328 @end ignore