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