]>
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) | |
d2c639d6 BS |
43 | @end table |
44 | ||
45 | Parameters to snapshot subcommand: | |
46 | ||
47 | @table @option | |
48 | ||
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 | |
acd935ef FB |
59 | @end table |
60 | ||
61 | Command description: | |
62 | ||
63 | @table @option | |
e6184690 KW |
64 | @item check [-f @var{fmt}] @var{filename} |
65 | ||
66 | Perform a consistency check on the disk image @var{filename}. | |
67 | ||
68 | Only the formats @code{qcow2}, @code{qed} and @code{vdi} support | |
69 | consistency checks. | |
70 | ||
8063d0fe | 71 | @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}] |
acd935ef FB |
72 | |
73 | Create the new disk image @var{filename} of size @var{size} and format | |
8063d0fe KW |
74 | @var{fmt}. Depending on the file format, you can add one or more @var{options} |
75 | that enable additional features of this format. | |
acd935ef | 76 | |
8063d0fe KW |
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). | |
acd935ef | 81 | |
eff44266 KW |
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. | |
84 | ||
acd935ef FB |
85 | @item commit [-f @var{fmt}] @var{filename} |
86 | ||
87 | Commit the changes recorded in @var{filename} in its base image. | |
88 | ||
aaf55b47 | 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} |
acd935ef | 90 | |
51ef6727 | 91 | Convert the disk image @var{filename} or a snapshot @var{snapshot_name} to disk image @var{output_filename} |
eff44266 KW |
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). | |
acd935ef | 94 | |
8063d0fe | 95 | Only the formats @code{qcow} and @code{qcow2} support compression. The |
acd935ef FB |
96 | compression is read-only. It means that if a compressed sector is |
97 | rewritten, then it is rewritten as uncompressed data. | |
98 | ||
acd935ef FB |
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. | |
102 | ||
8063d0fe KW |
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. | |
107 | ||
acd935ef FB |
108 | @item info [-f @var{fmt}] @var{filename} |
109 | ||
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 | |
19d36792 FB |
112 | from the displayed size. If VM snapshots are stored in the disk image, |
113 | they are displayed too. | |
d2c639d6 BS |
114 | |
115 | @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename} | |
116 | ||
117 | List, apply, create or delete snapshots in image @var{filename}. | |
ae6b0ed6 | 118 | |
aaf55b47 | 119 | @item rebase [-f @var{fmt}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename} |
e6184690 KW |
120 | |
121 | Changes the backing file of an image. Only the formats @code{qcow2} and | |
122 | @code{qed} support changing the backing file. | |
123 | ||
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}. | |
127 | ||
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. | |
134 | ||
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. | |
138 | ||
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. | |
141 | ||
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. | |
147 | ||
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 | |
152 | ||
ae6b0ed6 SH |
153 | @item resize @var{filename} [+ | -]@var{size} |
154 | ||
155 | Change the disk image as if it had been created with @var{size}. | |
156 | ||
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! | |
160 | ||
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. | |
acd935ef FB |
164 | @end table |
165 | ||
f932c040 KW |
166 | Supported image file formats: |
167 | ||
168 | @table @option | |
169 | @item raw | |
170 | ||
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. | |
177 | ||
f932c040 KW |
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. | |
8063d0fe | 183 | |
3e032364 KW |
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. | |
192 | ||
8063d0fe KW |
193 | Encryption uses the AES format which is very secure (128 bit keys). Use |
194 | a long password (16 characters) to get maximum protection. | |
3e032364 KW |
195 | |
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. | |
200 | ||
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. | |
205 | ||
206 | @end table | |
207 | ||
208 | ||
f932c040 KW |
209 | @item qcow |
210 | Old QEMU image format. Left for compatibility. | |
3e032364 KW |
211 | |
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 | |
219 | ||
f932c040 KW |
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. | |
3e032364 KW |
228 | |
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 | |
236 | ||
237 | @item vpc | |
238 | VirtualPC compatible image format (VHD). | |
239 | ||
f932c040 KW |
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 | |
244 | ||
245 | ||
acd935ef FB |
246 | @c man end |
247 | ||
248 | @ignore | |
249 | ||
250 | @setfilename qemu-img | |
251 | @settitle QEMU disk image utility | |
252 | ||
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 | |
257 | ||
258 | @c man begin AUTHOR | |
259 | Fabrice Bellard | |
260 | @c man end | |
261 | ||
262 | @end ignore |