1
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
4
.\" ========================================================================
5
.de Sp \" Vertical space (when we can't use .PP)
9
.de Vb \" Begin verbatim text
14
.de Ve \" End verbatim text
18
.\" Set up some character translations and predefined strings. \*(-- will
19
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23
.\" nothing in troff, for use with C<>.
25
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
43
.\" Escape single quotes in literal strings from groff's Unicode transform.
47
.\" If the F register is turned on, we'll generate index entries on stderr for
48
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49
.\" entries marked with X<> in POD. Of course, you'll have to process the
50
.\" output yourself in some meaningful fashion.
53
. tm Index:\\$1\t\\n%\t"\\$2"
63
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64
.\" Fear. Run. Save yourself. No user-serviceable parts.
65
. \" fudge factors for nroff and troff
74
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80
. \" simple accents for nroff and troff
90
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
97
. \" troff and (daisy-wheel) nroff accents
98
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105
.ds ae a\h'-(\w'a'u*4/10)'e
106
.ds Ae A\h'-(\w'A'u*4/10)'E
107
. \" corrections for vroff
108
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110
. \" for low resolution devices (crt and lpr)
111
.if \n(.H>23 .if \n(.V>19 \
124
.\" ========================================================================
126
.IX Title "QEMU-IMG 1"
127
.TH QEMU-IMG 1 "2012-01-11" " " " "
128
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129
.\" way too many mistakes in technical documents.
133
qemu\-img \- QEMU disk image utility
135
.IX Header "SYNOPSIS"
136
usage: qemu-img command [command options]
139
The following commands are supported:
140
.IP "\fBcheck [\-f\fR \fIfmt\fR\fB]\fR \fIfilename\fR" 4
141
.IX Item "check [-f fmt] filename"
143
.IP "\fBcreate [\-f\fR \fIfmt\fR\fB] [\-o\fR \fIoptions\fR\fB]\fR \fIfilename\fR \fB[\fR\fIsize\fR\fB]\fR" 4
144
.IX Item "create [-f fmt] [-o options] filename [size]"
145
.IP "\fBcommit [\-f\fR \fIfmt\fR\fB]\fR \fIfilename\fR" 4
146
.IX Item "commit [-f fmt] filename"
147
.IP "\fBconvert [\-c] [\-p] [\-f\fR \fIfmt\fR\fB] [\-O\fR \fIoutput_fmt\fR\fB] [\-o\fR \fIoptions\fR\fB] [\-s\fR \fIsnapshot_name\fR\fB] [\-S\fR \fIsparse_size\fR\fB]\fR \fIfilename\fR \fB[\fR\fIfilename2\fR \fB[...]]\fR \fIoutput_filename\fR" 4
148
.IX Item "convert [-c] [-p] [-f fmt] [-O output_fmt] [-o options] [-s snapshot_name] [-S sparse_size] filename [filename2 [...]] output_filename"
149
.IP "\fBinfo [\-f\fR \fIfmt\fR\fB]\fR \fIfilename\fR" 4
150
.IX Item "info [-f fmt] filename"
151
.IP "\fBsnapshot [\-l | \-a\fR \fIsnapshot\fR \fB| \-c\fR \fIsnapshot\fR \fB| \-d\fR \fIsnapshot\fR\fB]\fR \fIfilename\fR" 4
152
.IX Item "snapshot [-l | -a snapshot | -c snapshot | -d snapshot] filename"
153
.IP "\fBrebase [\-f\fR \fIfmt\fR\fB] [\-p] [\-u] \-b\fR \fIbacking_file\fR \fB[\-F\fR \fIbacking_fmt\fR\fB]\fR \fIfilename\fR" 4
154
.IX Item "rebase [-f fmt] [-p] [-u] -b backing_file [-F backing_fmt] filename"
155
.IP "\fBresize\fR \fIfilename\fR \fB[+ | \-]\fR\fIsize\fR" 4
156
.IX Item "resize filename [+ | -]size"
160
.IP "\fIfilename\fR" 4
163
\& is a disk image filename
167
is the disk image format. It is guessed automatically in most cases. See below
168
for a description of the supported disk formats.
171
is the disk image size in bytes. Optional suffixes \f(CW\*(C`k\*(C'\fR or \f(CW\*(C`K\*(C'\fR
172
(kilobyte, 1024) \f(CW\*(C`M\*(C'\fR (megabyte, 1024k) and \f(CW\*(C`G\*(C'\fR (gigabyte, 1024M)
173
and T (terabyte, 1024G) are supported. \f(CW\*(C`b\*(C'\fR is ignored.
174
.IP "\fIoutput_filename\fR" 4
175
.IX Item "output_filename"
176
is the destination disk image filename
177
.IP "\fIoutput_fmt\fR" 4
178
.IX Item "output_fmt"
180
\& is the destination format
182
.IP "\fIoptions\fR" 4
184
is a comma separated list of format specific options in a
185
name=value format. Use \f(CW\*(C`\-o ?\*(C'\fR for an overview of the options supported
186
by the used format or see the format descriptions below for details.
189
indicates that target image must be compressed (qcow format only)
192
with or without a command shows help and lists the supported formats
195
display progress bar (convert and rebase commands only)
196
.IP "\fI\-S\fR \fIsize\fR" 4
198
indicates the consecutive number of bytes that must contain only zeros
199
for qemu-img to create a sparse image during conversion. This value is rounded
200
down to the nearest 512 bytes. You may use the common size suffixes like
201
\&\f(CW\*(C`k\*(C'\fR for kilobytes.
203
Parameters to snapshot subcommand:
204
.IP "\fBsnapshot\fR" 4
206
is the name of the snapshot to create, apply or delete
209
applies a snapshot (revert disk to saved state)
218
lists all snapshots in the given image
221
.IP "\fBcheck [\-f\fR \fIfmt\fR\fB]\fR \fIfilename\fR" 4
222
.IX Item "check [-f fmt] filename"
223
Perform a consistency check on the disk image \fIfilename\fR.
225
Only the formats \f(CW\*(C`qcow2\*(C'\fR, \f(CW\*(C`qed\*(C'\fR and \f(CW\*(C`vdi\*(C'\fR support
227
.IP "\fBcreate [\-f\fR \fIfmt\fR\fB] [\-o\fR \fIoptions\fR\fB]\fR \fIfilename\fR \fB[\fR\fIsize\fR\fB]\fR" 4
228
.IX Item "create [-f fmt] [-o options] filename [size]"
229
Create the new disk image \fIfilename\fR of size \fIsize\fR and format
230
\&\fIfmt\fR. Depending on the file format, you can add one or more \fIoptions\fR
231
that enable additional features of this format.
233
If the option \fIbacking_file\fR is specified, then the image will record
234
only the differences from \fIbacking_file\fR. No size needs to be specified in
235
this case. \fIbacking_file\fR will never be modified unless you use the
236
\&\f(CW\*(C`commit\*(C'\fR monitor command (or qemu-img commit).
238
The size can also be specified using the \fIsize\fR option with \f(CW\*(C`\-o\*(C'\fR,
239
it doesn't need to be specified separately in this case.
240
.IP "\fBcommit [\-f\fR \fIfmt\fR\fB]\fR \fIfilename\fR" 4
241
.IX Item "commit [-f fmt] filename"
242
Commit the changes recorded in \fIfilename\fR in its base image.
243
.IP "\fBconvert [\-c] [\-p] [\-f\fR \fIfmt\fR\fB] [\-O\fR \fIoutput_fmt\fR\fB] [\-o\fR \fIoptions\fR\fB] [\-s\fR \fIsnapshot_name\fR\fB] [\-S\fR \fIsparse_size\fR\fB]\fR \fIfilename\fR \fB[\fR\fIfilename2\fR \fB[...]]\fR \fIoutput_filename\fR" 4
244
.IX Item "convert [-c] [-p] [-f fmt] [-O output_fmt] [-o options] [-s snapshot_name] [-S sparse_size] filename [filename2 [...]] output_filename"
245
Convert the disk image \fIfilename\fR or a snapshot \fIsnapshot_name\fR to disk image \fIoutput_filename\fR
246
using format \fIoutput_fmt\fR. It can be optionally compressed (\f(CW\*(C`\-c\*(C'\fR
247
option) or use any format specific options like encryption (\f(CW\*(C`\-o\*(C'\fR option).
249
Only the formats \f(CW\*(C`qcow\*(C'\fR and \f(CW\*(C`qcow2\*(C'\fR support compression. The
250
compression is read-only. It means that if a compressed sector is
251
rewritten, then it is rewritten as uncompressed data.
253
Image conversion is also useful to get smaller image when using a
254
growable format such as \f(CW\*(C`qcow\*(C'\fR or \f(CW\*(C`cow\*(C'\fR: the empty sectors
255
are detected and suppressed from the destination image.
257
You can use the \fIbacking_file\fR option to force the output image to be
258
created as a copy on write image of the specified base image; the
259
\&\fIbacking_file\fR should have the same content as the input's base image,
260
however the path, image format, etc may differ.
261
.IP "\fBinfo [\-f\fR \fIfmt\fR\fB]\fR \fIfilename\fR" 4
262
.IX Item "info [-f fmt] filename"
263
Give information about the disk image \fIfilename\fR. Use it in
264
particular to know the size reserved on disk which can be different
265
from the displayed size. If \s-1VM\s0 snapshots are stored in the disk image,
266
they are displayed too.
267
.IP "\fBsnapshot [\-l | \-a\fR \fIsnapshot\fR \fB| \-c\fR \fIsnapshot\fR \fB| \-d\fR \fIsnapshot\fR \fB]\fR \fIfilename\fR" 4
268
.IX Item "snapshot [-l | -a snapshot | -c snapshot | -d snapshot ] filename"
269
List, apply, create or delete snapshots in image \fIfilename\fR.
270
.IP "\fBrebase [\-f\fR \fIfmt\fR\fB] [\-p] [\-u] \-b\fR \fIbacking_file\fR \fB[\-F\fR \fIbacking_fmt\fR\fB]\fR \fIfilename\fR" 4
271
.IX Item "rebase [-f fmt] [-p] [-u] -b backing_file [-F backing_fmt] filename"
272
Changes the backing file of an image. Only the formats \f(CW\*(C`qcow2\*(C'\fR and
273
\&\f(CW\*(C`qed\*(C'\fR support changing the backing file.
275
The backing file is changed to \fIbacking_file\fR and (if the image format of
276
\&\fIfilename\fR supports this) the backing file format is changed to
279
There are two different modes in which \f(CW\*(C`rebase\*(C'\fR can operate:
281
.IP "\fBSafe mode\fR" 4
283
This is the default mode and performs a real rebase operation. The new backing
284
file may differ from the old one and qemu-img rebase will take care of keeping
285
the guest-visible content of \fIfilename\fR unchanged.
287
In order to achieve this, any clusters that differ between \fIbacking_file\fR
288
and the old backing file of \fIfilename\fR are merged into \fIfilename\fR
289
before actually changing the backing file.
291
Note that the safe mode is an expensive operation, comparable to converting
292
an image. It only works if the old backing file still exists.
293
.IP "\fBUnsafe mode\fR" 4
294
.IX Item "Unsafe mode"
295
qemu-img uses the unsafe mode if \f(CW\*(C`\-u\*(C'\fR is specified. In this mode, only the
296
backing file name and format of \fIfilename\fR is changed without any checks
297
on the file contents. The user must take care of specifying the correct new
298
backing file, or the guest-visible content of the image will be corrupted.
300
This mode is useful for renaming or moving the backing file to somewhere else.
301
It can be used without an accessible old backing file, i.e. you can use it to
302
fix an image whose backing file has already been moved/renamed.
306
.IP "\fBresize\fR \fIfilename\fR \fB[+ | \-]\fR\fIsize\fR" 4
307
.IX Item "resize filename [+ | -]size"
308
Change the disk image as if it had been created with \fIsize\fR.
310
Before using this command to shrink a disk image, you \s-1MUST\s0 use file system and
311
partitioning tools inside the \s-1VM\s0 to reduce allocated file systems and partition
312
sizes accordingly. Failure to do so will result in data loss!
314
After using this command to grow a disk image, you must use file system and
315
partitioning tools inside the \s-1VM\s0 to actually begin using the new space on the
318
Supported image file formats:
321
Raw disk image format (default). This format has the advantage of
322
being simple and easily exportable to all other emulators. If your
323
file system supports \fIholes\fR (for example in ext2 or ext3 on
324
Linux or \s-1NTFS\s0 on Windows), then only the written sectors will reserve
325
space. Use \f(CW\*(C`qemu\-img info\*(C'\fR to know the real size used by the
326
image or \f(CW\*(C`ls \-ls\*(C'\fR on Unix/Linux.
329
\&\s-1QEMU\s0 image format, the most versatile format. Use it to have smaller
330
images (useful if your filesystem does not supports holes, for example
331
on Windows), optional \s-1AES\s0 encryption, zlib based compression and
332
support of multiple \s-1VM\s0 snapshots.
336
.ie n .IP """backing_file""" 4
337
.el .IP "\f(CWbacking_file\fR" 4
338
.IX Item "backing_file"
339
File name of a base image (see \fBcreate\fR subcommand)
340
.ie n .IP """backing_fmt""" 4
341
.el .IP "\f(CWbacking_fmt\fR" 4
342
.IX Item "backing_fmt"
343
Image format of the base image
344
.ie n .IP """encryption""" 4
345
.el .IP "\f(CWencryption\fR" 4
346
.IX Item "encryption"
347
If this option is set to \f(CW\*(C`on\*(C'\fR, the image is encrypted.
349
Encryption uses the \s-1AES\s0 format which is very secure (128 bit keys). Use
350
a long password (16 characters) to get maximum protection.
351
.ie n .IP """cluster_size""" 4
352
.el .IP "\f(CWcluster_size\fR" 4
353
.IX Item "cluster_size"
354
Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
355
sizes can improve the image file size whereas larger cluster sizes generally
356
provide better performance.
357
.ie n .IP """preallocation""" 4
358
.el .IP "\f(CWpreallocation\fR" 4
359
.IX Item "preallocation"
360
Preallocation mode (allowed values: off, metadata). An image with preallocated
361
metadata is initially larger but can improve performance when the image needs
368
Old \s-1QEMU\s0 image format. Left for compatibility.
372
.ie n .IP """backing_file""" 4
373
.el .IP "\f(CWbacking_file\fR" 4
374
.IX Item "backing_file"
375
File name of a base image (see \fBcreate\fR subcommand)
376
.ie n .IP """encryption""" 4
377
.el .IP "\f(CWencryption\fR" 4
378
.IX Item "encryption"
379
If this option is set to \f(CW\*(C`on\*(C'\fR, the image is encrypted.
385
User Mode Linux Copy On Write image format. Used to be the only growable
386
image format in \s-1QEMU\s0. It is supported only for compatibility with
387
previous versions. It does not work on win32.
390
VirtualBox 1.1 compatible image format.
393
VMware 3 and 4 compatible image format.
397
.ie n .IP """backing_fmt""" 4
398
.el .IP "\f(CWbacking_fmt\fR" 4
399
.IX Item "backing_fmt"
400
Image format of the base image
401
.ie n .IP """compat6""" 4
402
.el .IP "\f(CWcompat6\fR" 4
404
Create a \s-1VMDK\s0 version 6 image (instead of version 4)
410
VirtualPC compatible image format (\s-1VHD\s0).
413
Linux Compressed Loop image, useful only to reuse directly compressed
414
CD-ROM images present for example in the Knoppix CD-ROMs.
416
.IX Header "SEE ALSO"
417
The \s-1HTML\s0 documentation of \s-1QEMU\s0 for more precise information and Linux
418
user mode emulator invocation.