blob: ac978542c2e40dfd28af38d3b65f8f649aaa483b [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
7@c man begin OPTIONS
8
9The following commands are supported:
Stuart Brady153859b2009-06-07 00:42:17 +010010
11@include qemu-img-cmds.texi
bellardacd935e2004-11-15 22:57:26 +000012
13Command parameters:
14@table @var
15@item filename
16 is a disk image filename
ths5fafdf22007-09-16 21:08:06 +000017@item fmt
Kevin Wolff932c042009-10-28 12:49:15 +010018is the disk image format. It is guessed automatically in most cases. See below
19for a description of the supported disk formats.
bellardacd935e2004-11-15 22:57:26 +000020
ths5fafdf22007-09-16 21:08:06 +000021@item size
Kevin Wolfeff44262009-06-04 15:39:39 +020022is 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.
bellardacd935e2004-11-15 22:57:26 +000025
26@item output_filename
ths5fafdf22007-09-16 21:08:06 +000027is the destination disk image filename
bellardacd935e2004-11-15 22:57:26 +000028
29@item output_fmt
30 is the destination format
Kevin Wolfeff44262009-06-04 15:39:39 +020031@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
Kevin Wolf3e032362009-10-28 12:49:17 +010034by the used format or see the format descriptions below for details.
Kevin Wolfeff44262009-06-04 15:39:39 +020035
bellardacd935e2004-11-15 22:57:26 +000036
37@item -c
38indicates that target image must be compressed (qcow format only)
blueswir1d2c639d2009-01-24 18:19:25 +000039@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
bellardacd935e2004-11-15 22:57:26 +000057@end table
58
59Command description:
60
61@table @option
Kevin Wolf8063d0f2009-10-28 12:49:16 +010062@item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
bellardacd935e2004-11-15 22:57:26 +000063
64Create the new disk image @var{filename} of size @var{size} and format
Kevin Wolf8063d0f2009-10-28 12:49:16 +010065@var{fmt}. Depending on the file format, you can add one or more @var{options}
66that enable additional features of this format.
bellardacd935e2004-11-15 22:57:26 +000067
Kevin Wolf8063d0f2009-10-28 12:49:16 +010068If the option @var{backing_file} is specified, then the image will record
69only the differences from @var{backing_file}. No size needs to be specified in
70this case. @var{backing_file} will never be modified unless you use the
71@code{commit} monitor command (or qemu-img commit).
bellardacd935e2004-11-15 22:57:26 +000072
Kevin Wolfeff44262009-06-04 15:39:39 +020073The size can also be specified using the @var{size} option with @code{-o},
74it doesn't need to be specified separately in this case.
75
bellardacd935e2004-11-15 22:57:26 +000076@item commit [-f @var{fmt}] @var{filename}
77
78Commit the changes recorded in @var{filename} in its base image.
79
Kevin Wolf8063d0f2009-10-28 12:49:16 +010080@item convert [-c] [-f @var{fmt}] [-O @var{output_fmt}] [-o @var{options}] @var{filename} [@var{filename2} [...]] @var{output_filename}
bellardacd935e2004-11-15 22:57:26 +000081
82Convert the disk image @var{filename} to disk image @var{output_filename}
Kevin Wolfeff44262009-06-04 15:39:39 +020083using format @var{output_fmt}. It can be optionally compressed (@code{-c}
84option) or use any format specific options like encryption (@code{-o} option).
bellardacd935e2004-11-15 22:57:26 +000085
Kevin Wolf8063d0f2009-10-28 12:49:16 +010086Only the formats @code{qcow} and @code{qcow2} support compression. The
bellardacd935e2004-11-15 22:57:26 +000087compression is read-only. It means that if a compressed sector is
88rewritten, then it is rewritten as uncompressed data.
89
bellardacd935e2004-11-15 22:57:26 +000090Image conversion is also useful to get smaller image when using a
91growable format such as @code{qcow} or @code{cow}: the empty sectors
92are detected and suppressed from the destination image.
93
Kevin Wolf8063d0f2009-10-28 12:49:16 +010094You can use the @var{backing_file} option to force the output image to be
95created as a copy on write image of the specified base image; the
96@var{backing_file} should have the same content as the input's base image,
97however the path, image format, etc may differ.
98
bellardacd935e2004-11-15 22:57:26 +000099@item info [-f @var{fmt}] @var{filename}
100
101Give information about the disk image @var{filename}. Use it in
102particular to know the size reserved on disk which can be different
bellard19d36792006-08-07 21:34:34 +0000103from the displayed size. If VM snapshots are stored in the disk image,
104they are displayed too.
blueswir1d2c639d2009-01-24 18:19:25 +0000105
106@item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
107
108List, apply, create or delete snapshots in image @var{filename}.
bellardacd935e2004-11-15 22:57:26 +0000109@end table
110
Kevin Wolff932c042009-10-28 12:49:15 +0100111Supported image file formats:
112
113@table @option
114@item raw
115
116Raw disk image format (default). This format has the advantage of
117being simple and easily exportable to all other emulators. If your
118file system supports @emph{holes} (for example in ext2 or ext3 on
119Linux or NTFS on Windows), then only the written sectors will reserve
120space. Use @code{qemu-img info} to know the real size used by the
121image or @code{ls -ls} on Unix/Linux.
122
123@item host_device
124
125Host device format. This format should be used instead of raw when
126converting to block devices or other devices where "holes" are not
127supported.
128
129@item qcow2
130QEMU image format, the most versatile format. Use it to have smaller
131images (useful if your filesystem does not supports holes, for example
132on Windows), optional AES encryption, zlib based compression and
133support of multiple VM snapshots.
Kevin Wolf8063d0f2009-10-28 12:49:16 +0100134
Kevin Wolf3e032362009-10-28 12:49:17 +0100135Supported options:
136@table @code
137@item backing_file
138File name of a base image (see @option{create} subcommand)
139@item backing_fmt
140Image format of the base image
141@item encryption
142If this option is set to @code{on}, the image is encrypted.
143
Kevin Wolf8063d0f2009-10-28 12:49:16 +0100144Encryption uses the AES format which is very secure (128 bit keys). Use
145a long password (16 characters) to get maximum protection.
Kevin Wolf3e032362009-10-28 12:49:17 +0100146
147@item cluster_size
148Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
149sizes can improve the image file size whereas larger cluster sizes generally
150provide better performance.
151
152@item preallocation
153Preallocation mode (allowed values: off, metadata). An image with preallocated
154metadata is initially larger but can improve performance when the image needs
155to grow.
156
157@end table
158
159
Kevin Wolff932c042009-10-28 12:49:15 +0100160@item qcow
161Old QEMU image format. Left for compatibility.
Kevin Wolf3e032362009-10-28 12:49:17 +0100162
163Supported options:
164@table @code
165@item backing_file
166File name of a base image (see @option{create} subcommand)
167@item encryption
168If this option is set to @code{on}, the image is encrypted.
169@end table
170
Kevin Wolff932c042009-10-28 12:49:15 +0100171@item cow
172User Mode Linux Copy On Write image format. Used to be the only growable
173image format in QEMU. It is supported only for compatibility with
174previous versions. It does not work on win32.
175@item vdi
176VirtualBox 1.1 compatible image format.
177@item vmdk
178VMware 3 and 4 compatible image format.
Kevin Wolf3e032362009-10-28 12:49:17 +0100179
180Supported options:
181@table @code
182@item backing_fmt
183Image format of the base image
184@item compat6
185Create a VMDK version 6 image (instead of version 4)
186@end table
187
188@item vpc
189VirtualPC compatible image format (VHD).
190
Kevin Wolff932c042009-10-28 12:49:15 +0100191@item cloop
192Linux Compressed Loop image, useful only to reuse directly compressed
193CD-ROM images present for example in the Knoppix CD-ROMs.
194@end table
195
196
bellardacd935e2004-11-15 22:57:26 +0000197@c man end
198
199@ignore
200
201@setfilename qemu-img
202@settitle QEMU disk image utility
203
204@c man begin SEEALSO
205The HTML documentation of QEMU for more precise information and Linux
206user mode emulator invocation.
207@c man end
208
209@c man begin AUTHOR
210Fabrice Bellard
211@c man end
212
213@end ignore