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