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