xref: /illumos-kvm-cmd/qemu-img.texi (revision 68396ea9)
1@example
2@c man begin SYNOPSIS
3usage: qemu-img command [command options]
4@c man end
5@end example
6
7@c man begin OPTIONS
8
9The following commands are supported:
10
11@include qemu-img-cmds.texi
12
13Command parameters:
14@table @var
15@item filename
16 is a disk image filename
17@item fmt
18is the disk image format. It is guessed automatically in most cases. See below
19for a description of the supported disk formats.
20
21@item size
22is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
23(kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)
24and T (terabyte, 1024G) are supported.  @code{b} is ignored.
25
26@item output_filename
27is the destination disk image filename
28
29@item output_fmt
30 is the destination format
31@item options
32is a comma separated list of format specific options in a
33name=value format. Use @code{-o ?} for an overview of the options supported
34by the used format or see the format descriptions below for details.
35
36
37@item -c
38indicates that target image must be compressed (qcow format only)
39@item -h
40with or without a command shows help and lists the supported formats
41@end table
42
43Parameters to snapshot subcommand:
44
45@table @option
46
47@item snapshot
48is the name of the snapshot to create, apply or delete
49@item -a
50applies a snapshot (revert disk to saved state)
51@item -c
52creates a snapshot
53@item -d
54deletes a snapshot
55@item -l
56lists all snapshots in the given image
57@end table
58
59Command description:
60
61@table @option
62@item check [-f @var{fmt}] @var{filename}
63
64Perform a consistency check on the disk image @var{filename}.
65
66Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
67consistency checks.
68
69@item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
70
71Create the new disk image @var{filename} of size @var{size} and format
72@var{fmt}. Depending on the file format, you can add one or more @var{options}
73that enable additional features of this format.
74
75If the option @var{backing_file} is specified, then the image will record
76only the differences from @var{backing_file}. No size needs to be specified in
77this case. @var{backing_file} will never be modified unless you use the
78@code{commit} monitor command (or qemu-img commit).
79
80The size can also be specified using the @var{size} option with @code{-o},
81it doesn't need to be specified separately in this case.
82
83@item commit [-f @var{fmt}] @var{filename}
84
85Commit the changes recorded in @var{filename} in its base image.
86
87@item convert [-c] [-f @var{fmt}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_name}] @var{filename} [@var{filename2} [...]] @var{output_filename}
88
89Convert the disk image @var{filename} or a snapshot @var{snapshot_name} to disk image @var{output_filename}
90using format @var{output_fmt}. It can be optionally compressed (@code{-c}
91option) or use any format specific options like encryption (@code{-o} option).
92
93Only the formats @code{qcow} and @code{qcow2} support compression. The
94compression is read-only. It means that if a compressed sector is
95rewritten, then it is rewritten as uncompressed data.
96
97Image conversion is also useful to get smaller image when using a
98growable format such as @code{qcow} or @code{cow}: the empty sectors
99are detected and suppressed from the destination image.
100
101You can use the @var{backing_file} option to force the output image to be
102created as a copy on write image of the specified base image; the
103@var{backing_file} should have the same content as the input's base image,
104however the path, image format, etc may differ.
105
106@item info [-f @var{fmt}] @var{filename}
107
108Give information about the disk image @var{filename}. Use it in
109particular to know the size reserved on disk which can be different
110from the displayed size. If VM snapshots are stored in the disk image,
111they are displayed too.
112
113@item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
114
115List, apply, create or delete snapshots in image @var{filename}.
116
117@item rebase [-f @var{fmt}] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
118
119Changes the backing file of an image. Only the formats @code{qcow2} and
120@code{qed} support changing the backing file.
121
122The backing file is changed to @var{backing_file} and (if the image format of
123@var{filename} supports this) the backing file format is changed to
124@var{backing_fmt}.
125
126There are two different modes in which @code{rebase} can operate:
127@table @option
128@item Safe mode
129This is the default mode and performs a real rebase operation. The new backing
130file may differ from the old one and qemu-img rebase will take care of keeping
131the guest-visible content of @var{filename} unchanged.
132
133In order to achieve this, any clusters that differ between @var{backing_file}
134and the old backing file of @var{filename} are merged into @var{filename}
135before actually changing the backing file.
136
137Note that the safe mode is an expensive operation, comparable to converting
138an image. It only works if the old backing file still exists.
139
140@item Unsafe mode
141qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the
142backing file name and format of @var{filename} is changed without any checks
143on the file contents. The user must take care of specifying the correct new
144backing file, or the guest-visible content of the image will be corrupted.
145
146This mode is useful for renaming or moving the backing file to somewhere else.
147It can be used without an accessible old backing file, i.e. you can use it to
148fix an image whose backing file has already been moved/renamed.
149@end table
150
151@item resize @var{filename} [+ | -]@var{size}
152
153Change the disk image as if it had been created with @var{size}.
154
155Before using this command to shrink a disk image, you MUST use file system and
156partitioning tools inside the VM to reduce allocated file systems and partition
157sizes accordingly.  Failure to do so will result in data loss!
158
159After using this command to grow a disk image, you must use file system and
160partitioning tools inside the VM to actually begin using the new space on the
161device.
162@end table
163
164Supported image file formats:
165
166@table @option
167@item raw
168
169Raw disk image format (default). This format has the advantage of
170being simple and easily exportable to all other emulators. If your
171file system supports @emph{holes} (for example in ext2 or ext3 on
172Linux or NTFS on Windows), then only the written sectors will reserve
173space. Use @code{qemu-img info} to know the real size used by the
174image or @code{ls -ls} on Unix/Linux.
175
176@item host_device
177
178Host device format. This format should be used instead of raw when
179converting to block devices or other devices where "holes" are not
180supported.
181
182@item qcow2
183QEMU image format, the most versatile format. Use it to have smaller
184images (useful if your filesystem does not supports holes, for example
185on Windows), optional AES encryption, zlib based compression and
186support of multiple VM snapshots.
187
188Supported options:
189@table @code
190@item backing_file
191File name of a base image (see @option{create} subcommand)
192@item backing_fmt
193Image format of the base image
194@item encryption
195If this option is set to @code{on}, the image is encrypted.
196
197Encryption uses the AES format which is very secure (128 bit keys). Use
198a long password (16 characters) to get maximum protection.
199
200@item cluster_size
201Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
202sizes can improve the image file size whereas larger cluster sizes generally
203provide better performance.
204
205@item preallocation
206Preallocation mode (allowed values: off, metadata). An image with preallocated
207metadata is initially larger but can improve performance when the image needs
208to grow.
209
210@end table
211
212
213@item qcow
214Old QEMU image format. Left for compatibility.
215
216Supported options:
217@table @code
218@item backing_file
219File name of a base image (see @option{create} subcommand)
220@item encryption
221If this option is set to @code{on}, the image is encrypted.
222@end table
223
224@item cow
225User Mode Linux Copy On Write image format. Used to be the only growable
226image format in QEMU. It is supported only for compatibility with
227previous versions. It does not work on win32.
228@item vdi
229VirtualBox 1.1 compatible image format.
230@item vmdk
231VMware 3 and 4 compatible image format.
232
233Supported options:
234@table @code
235@item backing_fmt
236Image format of the base image
237@item compat6
238Create a VMDK version 6 image (instead of version 4)
239@end table
240
241@item vpc
242VirtualPC compatible image format (VHD).
243
244@item cloop
245Linux Compressed Loop image, useful only to reuse directly compressed
246CD-ROM images present for example in the Knoppix CD-ROMs.
247@end table
248
249
250@c man end
251
252@ignore
253
254@setfilename qemu-img
255@settitle QEMU disk image utility
256
257@c man begin SEEALSO
258The HTML documentation of QEMU for more precise information and Linux
259user mode emulator invocation.
260@c man end
261
262@c man begin AUTHOR
263Fabrice Bellard
264@c man end
265
266@end ignore
267