root / qemu-img.texi @ f53f81e0
History | View | Annotate | Download (18.8 kB)
1 | acd935ef | bellard | @example |
---|---|---|---|
2 | acd935ef | bellard | @c man begin SYNOPSIS |
3 | acd935ef | bellard | usage: qemu-img command [command options] |
4 | acd935ef | bellard | @c man end |
5 | acd935ef | bellard | @end example |
6 | acd935ef | bellard | |
7 | 48467328 | Kevin Wolf | @c man begin DESCRIPTION |
8 | 48467328 | Kevin Wolf | qemu-img allows you to create, convert and modify images offline. It can handle |
9 | 48467328 | Kevin Wolf | all image formats supported by QEMU. |
10 | 48467328 | Kevin Wolf | |
11 | 48467328 | Kevin Wolf | @b{Warning:} Never use qemu-img to modify images in use by a running virtual |
12 | 48467328 | Kevin Wolf | machine or any other process; this may destroy the image. Also, be aware that |
13 | 48467328 | Kevin Wolf | querying an image that is being modified by another process may encounter |
14 | 48467328 | Kevin Wolf | inconsistent state. |
15 | 48467328 | Kevin Wolf | @c man end |
16 | 48467328 | Kevin Wolf | |
17 | acd935ef | bellard | @c man begin OPTIONS |
18 | acd935ef | bellard | |
19 | acd935ef | bellard | The following commands are supported: |
20 | 153859be | Stuart Brady | |
21 | 153859be | Stuart Brady | @include qemu-img-cmds.texi |
22 | acd935ef | bellard | |
23 | acd935ef | bellard | Command parameters: |
24 | acd935ef | bellard | @table @var |
25 | acd935ef | bellard | @item filename |
26 | acd935ef | bellard | is a disk image filename |
27 | 5fafdf24 | ths | @item fmt |
28 | f932c040 | Kevin Wolf | is the disk image format. It is guessed automatically in most cases. See below |
29 | f932c040 | Kevin Wolf | for a description of the supported disk formats. |
30 | acd935ef | bellard | |
31 | e5357560 | Kashyap Chamarthy | @item --backing-chain |
32 | e5357560 | Kashyap Chamarthy | will enumerate information about backing files in a disk image chain. Refer |
33 | e5357560 | Kashyap Chamarthy | below for further description. |
34 | e5357560 | Kashyap Chamarthy | |
35 | 5fafdf24 | ths | @item size |
36 | eff44266 | Kevin Wolf | is the disk image size in bytes. Optional suffixes @code{k} or @code{K} |
37 | eff44266 | Kevin Wolf | (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M) |
38 | eff44266 | Kevin Wolf | and T (terabyte, 1024G) are supported. @code{b} is ignored. |
39 | acd935ef | bellard | |
40 | acd935ef | bellard | @item output_filename |
41 | 5fafdf24 | ths | is the destination disk image filename |
42 | acd935ef | bellard | |
43 | acd935ef | bellard | @item output_fmt |
44 | acd935ef | bellard | is the destination format |
45 | eff44266 | Kevin Wolf | @item options |
46 | eff44266 | Kevin Wolf | is a comma separated list of format specific options in a |
47 | eff44266 | Kevin Wolf | name=value format. Use @code{-o ?} for an overview of the options supported |
48 | 3e032364 | Kevin Wolf | by the used format or see the format descriptions below for details. |
49 | ef80654d | Wenchao Xia | @item snapshot_param |
50 | ef80654d | Wenchao Xia | is param used for internal snapshot, format is |
51 | ef80654d | Wenchao Xia | 'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]' |
52 | ef80654d | Wenchao Xia | @item snapshot_id_or_name |
53 | ef80654d | Wenchao Xia | is deprecated, use snapshot_param instead |
54 | acd935ef | bellard | |
55 | acd935ef | bellard | @item -c |
56 | acd935ef | bellard | indicates that target image must be compressed (qcow format only) |
57 | d2c639d6 | blueswir1 | @item -h |
58 | d2c639d6 | blueswir1 | with or without a command shows help and lists the supported formats |
59 | aaf55b47 | Jes Sorensen | @item -p |
60 | 0e3bd993 | Kevin Wolf | display progress bar (compare, convert and rebase commands only). |
61 | 0e3bd993 | Kevin Wolf | If the @var{-p} option is not used for a command that supports it, the |
62 | 0e3bd993 | Kevin Wolf | progress is reported when the process receives a @code{SIGUSR1} signal. |
63 | f382d43a | Miroslav Rezanina | @item -q |
64 | f382d43a | Miroslav Rezanina | Quiet mode - do not print any output (except errors). There's no progress bar |
65 | f382d43a | Miroslav Rezanina | in case both @var{-q} and @var{-p} options are used. |
66 | a22f123c | Kevin Wolf | @item -S @var{size} |
67 | a22f123c | Kevin Wolf | indicates the consecutive number of bytes that must contain only zeros |
68 | a22f123c | Kevin Wolf | for qemu-img to create a sparse image during conversion. This value is rounded |
69 | a22f123c | Kevin Wolf | down to the nearest 512 bytes. You may use the common size suffixes like |
70 | a22f123c | Kevin Wolf | @code{k} for kilobytes. |
71 | 3763f26f | Kevin Wolf | @item -t @var{cache} |
72 | 3763f26f | Kevin Wolf | specifies the cache mode that should be used with the (destination) file. See |
73 | 3763f26f | Kevin Wolf | the documentation of the emulator's @code{-drive cache=...} option for allowed |
74 | 3763f26f | Kevin Wolf | values. |
75 | d2c639d6 | blueswir1 | @end table |
76 | d2c639d6 | blueswir1 | |
77 | d2c639d6 | blueswir1 | Parameters to snapshot subcommand: |
78 | d2c639d6 | blueswir1 | |
79 | d2c639d6 | blueswir1 | @table @option |
80 | d2c639d6 | blueswir1 | |
81 | d2c639d6 | blueswir1 | @item snapshot |
82 | d2c639d6 | blueswir1 | is the name of the snapshot to create, apply or delete |
83 | d2c639d6 | blueswir1 | @item -a |
84 | d2c639d6 | blueswir1 | applies a snapshot (revert disk to saved state) |
85 | d2c639d6 | blueswir1 | @item -c |
86 | d2c639d6 | blueswir1 | creates a snapshot |
87 | d2c639d6 | blueswir1 | @item -d |
88 | d2c639d6 | blueswir1 | deletes a snapshot |
89 | d2c639d6 | blueswir1 | @item -l |
90 | d2c639d6 | blueswir1 | lists all snapshots in the given image |
91 | acd935ef | bellard | @end table |
92 | acd935ef | bellard | |
93 | d14ed18c | Miroslav Rezanina | Parameters to compare subcommand: |
94 | d14ed18c | Miroslav Rezanina | |
95 | d14ed18c | Miroslav Rezanina | @table @option |
96 | d14ed18c | Miroslav Rezanina | |
97 | d14ed18c | Miroslav Rezanina | @item -f |
98 | d14ed18c | Miroslav Rezanina | First image format |
99 | d14ed18c | Miroslav Rezanina | @item -F |
100 | d14ed18c | Miroslav Rezanina | Second image format |
101 | d14ed18c | Miroslav Rezanina | @item -s |
102 | d14ed18c | Miroslav Rezanina | Strict mode - fail on on different image size or sector allocation |
103 | d14ed18c | Miroslav Rezanina | @end table |
104 | d14ed18c | Miroslav Rezanina | |
105 | b2e10493 | Alexandre Derumier | Parameters to convert subcommand: |
106 | b2e10493 | Alexandre Derumier | |
107 | b2e10493 | Alexandre Derumier | @table @option |
108 | b2e10493 | Alexandre Derumier | |
109 | b2e10493 | Alexandre Derumier | @item -n |
110 | b2e10493 | Alexandre Derumier | Skip the creation of the target volume |
111 | b2e10493 | Alexandre Derumier | @end table |
112 | b2e10493 | Alexandre Derumier | |
113 | acd935ef | bellard | Command description: |
114 | acd935ef | bellard | |
115 | acd935ef | bellard | @table @option |
116 | 8599ea4c | Federico Simoncelli | @item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] @var{filename} |
117 | e6184690 | Kevin Wolf | |
118 | 8599ea4c | Federico Simoncelli | Perform a consistency check on the disk image @var{filename}. The command can |
119 | 8599ea4c | Federico Simoncelli | output in the format @var{ofmt} which is either @code{human} or @code{json}. |
120 | e6184690 | Kevin Wolf | |
121 | 4534ff54 | Kevin Wolf | If @code{-r} is specified, qemu-img tries to repair any inconsistencies found |
122 | 4534ff54 | Kevin Wolf | during the check. @code{-r leaks} repairs only cluster leaks, whereas |
123 | 4534ff54 | Kevin Wolf | @code{-r all} fixes all kinds of errors, with a higher risk of choosing the |
124 | 0546b8c2 | Stefan Weil | wrong fix or hiding corruption that has already occurred. |
125 | 4534ff54 | Kevin Wolf | |
126 | e6184690 | Kevin Wolf | Only the formats @code{qcow2}, @code{qed} and @code{vdi} support |
127 | e6184690 | Kevin Wolf | consistency checks. |
128 | e6184690 | Kevin Wolf | |
129 | 8063d0fe | Kevin Wolf | @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}] |
130 | acd935ef | bellard | |
131 | acd935ef | bellard | Create the new disk image @var{filename} of size @var{size} and format |
132 | 8063d0fe | Kevin Wolf | @var{fmt}. Depending on the file format, you can add one or more @var{options} |
133 | 8063d0fe | Kevin Wolf | that enable additional features of this format. |
134 | acd935ef | bellard | |
135 | 8063d0fe | Kevin Wolf | If the option @var{backing_file} is specified, then the image will record |
136 | 8063d0fe | Kevin Wolf | only the differences from @var{backing_file}. No size needs to be specified in |
137 | 8063d0fe | Kevin Wolf | this case. @var{backing_file} will never be modified unless you use the |
138 | 8063d0fe | Kevin Wolf | @code{commit} monitor command (or qemu-img commit). |
139 | acd935ef | bellard | |
140 | eff44266 | Kevin Wolf | The size can also be specified using the @var{size} option with @code{-o}, |
141 | eff44266 | Kevin Wolf | it doesn't need to be specified separately in this case. |
142 | eff44266 | Kevin Wolf | |
143 | 3763f26f | Kevin Wolf | @item commit [-f @var{fmt}] [-t @var{cache}] @var{filename} |
144 | acd935ef | bellard | |
145 | 37222900 | Jeff Cody | Commit the changes recorded in @var{filename} in its base image or backing file. |
146 | 37222900 | Jeff Cody | If the backing file is smaller than the snapshot, then the backing file will be |
147 | 37222900 | Jeff Cody | resized to be the same size as the snapshot. If the snapshot is smaller than |
148 | 37222900 | Jeff Cody | the backing file, the backing file will not be truncated. If you want the |
149 | 37222900 | Jeff Cody | backing file to match the size of the smaller snapshot, you can safely truncate |
150 | 37222900 | Jeff Cody | it yourself once the commit operation successfully completes. |
151 | acd935ef | bellard | |
152 | d14ed18c | Miroslav Rezanina | @item compare [-f @var{fmt}] [-F @var{fmt}] [-p] [-s] [-q] @var{filename1} @var{filename2} |
153 | d14ed18c | Miroslav Rezanina | |
154 | d14ed18c | Miroslav Rezanina | Check if two images have the same content. You can compare images with |
155 | d14ed18c | Miroslav Rezanina | different format or settings. |
156 | d14ed18c | Miroslav Rezanina | |
157 | d14ed18c | Miroslav Rezanina | The format is probed unless you specify it by @var{-f} (used for |
158 | d14ed18c | Miroslav Rezanina | @var{filename1}) and/or @var{-F} (used for @var{filename2}) option. |
159 | d14ed18c | Miroslav Rezanina | |
160 | d14ed18c | Miroslav Rezanina | By default, images with different size are considered identical if the larger |
161 | d14ed18c | Miroslav Rezanina | image contains only unallocated and/or zeroed sectors in the area after the end |
162 | d14ed18c | Miroslav Rezanina | of the other image. In addition, if any sector is not allocated in one image |
163 | d14ed18c | Miroslav Rezanina | and contains only zero bytes in the second one, it is evaluated as equal. You |
164 | d14ed18c | Miroslav Rezanina | can use Strict mode by specifying the @var{-s} option. When compare runs in |
165 | d14ed18c | Miroslav Rezanina | Strict mode, it fails in case image size differs or a sector is allocated in |
166 | d14ed18c | Miroslav Rezanina | one image and is not allocated in the second one. |
167 | d14ed18c | Miroslav Rezanina | |
168 | d14ed18c | Miroslav Rezanina | By default, compare prints out a result message. This message displays |
169 | d14ed18c | Miroslav Rezanina | information that both images are same or the position of the first different |
170 | d14ed18c | Miroslav Rezanina | byte. In addition, result message can report different image size in case |
171 | d14ed18c | Miroslav Rezanina | Strict mode is used. |
172 | d14ed18c | Miroslav Rezanina | |
173 | d14ed18c | Miroslav Rezanina | Compare exits with @code{0} in case the images are equal and with @code{1} |
174 | d14ed18c | Miroslav Rezanina | in case the images differ. Other exit codes mean an error occurred during |
175 | d14ed18c | Miroslav Rezanina | execution and standard error output should contain an error message. |
176 | d14ed18c | Miroslav Rezanina | The following table sumarizes all exit codes of the compare subcommand: |
177 | d14ed18c | Miroslav Rezanina | |
178 | d14ed18c | Miroslav Rezanina | @table @option |
179 | d14ed18c | Miroslav Rezanina | |
180 | d14ed18c | Miroslav Rezanina | @item 0 |
181 | d14ed18c | Miroslav Rezanina | Images are identical |
182 | d14ed18c | Miroslav Rezanina | @item 1 |
183 | d14ed18c | Miroslav Rezanina | Images differ |
184 | d14ed18c | Miroslav Rezanina | @item 2 |
185 | d14ed18c | Miroslav Rezanina | Error on opening an image |
186 | d14ed18c | Miroslav Rezanina | @item 3 |
187 | d14ed18c | Miroslav Rezanina | Error on checking a sector allocation |
188 | d14ed18c | Miroslav Rezanina | @item 4 |
189 | d14ed18c | Miroslav Rezanina | Error on reading data |
190 | d14ed18c | Miroslav Rezanina | |
191 | d14ed18c | Miroslav Rezanina | @end table |
192 | d14ed18c | Miroslav Rezanina | |
193 | ef80654d | Wenchao Xia | @item convert [-c] [-p] [-n] [-f @var{fmt}] [-t @var{cache}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_id_or_name}] [-l @var{snapshot_param}] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename} |
194 | acd935ef | bellard | |
195 | ef80654d | Wenchao Xia | Convert the disk image @var{filename} or a snapshot @var{snapshot_param}(@var{snapshot_id_or_name} is deprecated) |
196 | ef80654d | Wenchao Xia | to disk image @var{output_filename} using format @var{output_fmt}. It can be optionally compressed (@code{-c} |
197 | eff44266 | Kevin Wolf | option) or use any format specific options like encryption (@code{-o} option). |
198 | acd935ef | bellard | |
199 | 8063d0fe | Kevin Wolf | Only the formats @code{qcow} and @code{qcow2} support compression. The |
200 | acd935ef | bellard | compression is read-only. It means that if a compressed sector is |
201 | acd935ef | bellard | rewritten, then it is rewritten as uncompressed data. |
202 | acd935ef | bellard | |
203 | acd935ef | bellard | Image conversion is also useful to get smaller image when using a |
204 | acd935ef | bellard | growable format such as @code{qcow} or @code{cow}: the empty sectors |
205 | acd935ef | bellard | are detected and suppressed from the destination image. |
206 | acd935ef | bellard | |
207 | 11b6699a | Peter Lieven | @var{sparse_size} indicates the consecutive number of bytes (defaults to 4k) |
208 | 11b6699a | Peter Lieven | that must contain only zeros for qemu-img to create a sparse image during |
209 | 11b6699a | Peter Lieven | conversion. If @var{sparse_size} is 0, the source will not be scanned for |
210 | 11b6699a | Peter Lieven | unallocated or zero sectors, and the destination image will always be |
211 | 11b6699a | Peter Lieven | fully allocated. |
212 | 11b6699a | Peter Lieven | |
213 | 8063d0fe | Kevin Wolf | You can use the @var{backing_file} option to force the output image to be |
214 | 8063d0fe | Kevin Wolf | created as a copy on write image of the specified base image; the |
215 | 8063d0fe | Kevin Wolf | @var{backing_file} should have the same content as the input's base image, |
216 | 8063d0fe | Kevin Wolf | however the path, image format, etc may differ. |
217 | 8063d0fe | Kevin Wolf | |
218 | b2e10493 | Alexandre Derumier | If the @code{-n} option is specified, the target volume creation will be |
219 | b2e10493 | Alexandre Derumier | skipped. This is useful for formats such as @code{rbd} if the target |
220 | b2e10493 | Alexandre Derumier | volume has already been created with site specific options that cannot |
221 | b2e10493 | Alexandre Derumier | be supplied through qemu-img. |
222 | b2e10493 | Alexandre Derumier | |
223 | e5357560 | Kashyap Chamarthy | @item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename} |
224 | acd935ef | bellard | |
225 | acd935ef | bellard | Give information about the disk image @var{filename}. Use it in |
226 | acd935ef | bellard | particular to know the size reserved on disk which can be different |
227 | 19d36792 | bellard | from the displayed size. If VM snapshots are stored in the disk image, |
228 | c054b3fd | Benoรฎt Canet | they are displayed too. The command can output in the format @var{ofmt} |
229 | c054b3fd | Benoรฎt Canet | which is either @code{human} or @code{json}. |
230 | d2c639d6 | blueswir1 | |
231 | e5357560 | Kashyap Chamarthy | If a disk image has a backing file chain, information about each disk image in |
232 | e5357560 | Kashyap Chamarthy | the chain can be recursively enumerated by using the option @code{--backing-chain}. |
233 | e5357560 | Kashyap Chamarthy | |
234 | e5357560 | Kashyap Chamarthy | For instance, if you have an image chain like: |
235 | e5357560 | Kashyap Chamarthy | |
236 | e5357560 | Kashyap Chamarthy | @example |
237 | e5357560 | Kashyap Chamarthy | base.qcow2 <- snap1.qcow2 <- snap2.qcow2 |
238 | e5357560 | Kashyap Chamarthy | @end example |
239 | e5357560 | Kashyap Chamarthy | |
240 | e5357560 | Kashyap Chamarthy | To enumerate information about each disk image in the above chain, starting from top to base, do: |
241 | e5357560 | Kashyap Chamarthy | |
242 | e5357560 | Kashyap Chamarthy | @example |
243 | e5357560 | Kashyap Chamarthy | qemu-img info --backing-chain snap2.qcow2 |
244 | e5357560 | Kashyap Chamarthy | @end example |
245 | e5357560 | Kashyap Chamarthy | |
246 | facd6e2b | Paolo Bonzini | @item map [-f @var{fmt}] [--output=@var{ofmt}] @var{filename} |
247 | facd6e2b | Paolo Bonzini | |
248 | facd6e2b | Paolo Bonzini | Dump the metadata of image @var{filename} and its backing file chain. |
249 | facd6e2b | Paolo Bonzini | In particular, this commands dumps the allocation state of every sector |
250 | facd6e2b | Paolo Bonzini | of @var{filename}, together with the topmost file that allocates it in |
251 | facd6e2b | Paolo Bonzini | the backing file chain. |
252 | facd6e2b | Paolo Bonzini | |
253 | facd6e2b | Paolo Bonzini | Two option formats are possible. The default format (@code{human}) |
254 | facd6e2b | Paolo Bonzini | only dumps known-nonzero areas of the file. Known-zero parts of the |
255 | facd6e2b | Paolo Bonzini | file are omitted altogether, and likewise for parts that are not allocated |
256 | facd6e2b | Paolo Bonzini | throughout the chain. @command{qemu-img} output will identify a file |
257 | facd6e2b | Paolo Bonzini | from where the data can be read, and the offset in the file. Each line |
258 | facd6e2b | Paolo Bonzini | will include four fields, the first three of which are hexadecimal |
259 | facd6e2b | Paolo Bonzini | numbers. For example the first line of: |
260 | facd6e2b | Paolo Bonzini | @example |
261 | facd6e2b | Paolo Bonzini | Offset Length Mapped to File |
262 | facd6e2b | Paolo Bonzini | 0 0x20000 0x50000 /tmp/overlay.qcow2 |
263 | facd6e2b | Paolo Bonzini | 0x100000 0x10000 0x95380000 /tmp/backing.qcow2 |
264 | facd6e2b | Paolo Bonzini | @end example |
265 | facd6e2b | Paolo Bonzini | @noindent |
266 | facd6e2b | Paolo Bonzini | means that 0x20000 (131072) bytes starting at offset 0 in the image are |
267 | facd6e2b | Paolo Bonzini | available in /tmp/overlay.qcow2 (opened in @code{raw} format) starting |
268 | facd6e2b | Paolo Bonzini | at offset 0x50000 (327680). Data that is compressed, encrypted, or |
269 | facd6e2b | Paolo Bonzini | otherwise not available in raw format will cause an error if @code{human} |
270 | facd6e2b | Paolo Bonzini | format is in use. Note that file names can include newlines, thus it is |
271 | facd6e2b | Paolo Bonzini | not safe to parse this output format in scripts. |
272 | facd6e2b | Paolo Bonzini | |
273 | facd6e2b | Paolo Bonzini | The alternative format @code{json} will return an array of dictionaries |
274 | facd6e2b | Paolo Bonzini | in JSON format. It will include similar information in |
275 | facd6e2b | Paolo Bonzini | the @code{start}, @code{length}, @code{offset} fields; |
276 | facd6e2b | Paolo Bonzini | it will also include other more specific information: |
277 | facd6e2b | Paolo Bonzini | @itemize @minus |
278 | facd6e2b | Paolo Bonzini | @item |
279 | facd6e2b | Paolo Bonzini | whether the sectors contain actual data or not (boolean field @code{data}; |
280 | facd6e2b | Paolo Bonzini | if false, the sectors are either unallocated or stored as optimized |
281 | facd6e2b | Paolo Bonzini | all-zero clusters); |
282 | facd6e2b | Paolo Bonzini | |
283 | facd6e2b | Paolo Bonzini | @item |
284 | facd6e2b | Paolo Bonzini | whether the data is known to read as zero (boolean field @code{zero}); |
285 | facd6e2b | Paolo Bonzini | |
286 | facd6e2b | Paolo Bonzini | @item |
287 | facd6e2b | Paolo Bonzini | in order to make the output shorter, the target file is expressed as |
288 | facd6e2b | Paolo Bonzini | a @code{depth}; for example, a depth of 2 refers to the backing file |
289 | facd6e2b | Paolo Bonzini | of the backing file of @var{filename}. |
290 | facd6e2b | Paolo Bonzini | @end itemize |
291 | facd6e2b | Paolo Bonzini | |
292 | facd6e2b | Paolo Bonzini | In JSON format, the @code{offset} field is optional; it is absent in |
293 | facd6e2b | Paolo Bonzini | cases where @code{human} format would omit the entry or exit with an error. |
294 | facd6e2b | Paolo Bonzini | If @code{data} is false and the @code{offset} field is present, the |
295 | facd6e2b | Paolo Bonzini | corresponding sectors in the file are not yet in use, but they are |
296 | facd6e2b | Paolo Bonzini | preallocated. |
297 | facd6e2b | Paolo Bonzini | |
298 | facd6e2b | Paolo Bonzini | For more information, consult @file{include/block/block.h} in QEMU's |
299 | facd6e2b | Paolo Bonzini | source code. |
300 | facd6e2b | Paolo Bonzini | |
301 | d2c639d6 | blueswir1 | @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename} |
302 | d2c639d6 | blueswir1 | |
303 | d2c639d6 | blueswir1 | List, apply, create or delete snapshots in image @var{filename}. |
304 | ae6b0ed6 | Stefan Hajnoczi | |
305 | 3763f26f | Kevin Wolf | @item rebase [-f @var{fmt}] [-t @var{cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename} |
306 | e6184690 | Kevin Wolf | |
307 | e6184690 | Kevin Wolf | Changes the backing file of an image. Only the formats @code{qcow2} and |
308 | e6184690 | Kevin Wolf | @code{qed} support changing the backing file. |
309 | e6184690 | Kevin Wolf | |
310 | e6184690 | Kevin Wolf | The backing file is changed to @var{backing_file} and (if the image format of |
311 | e6184690 | Kevin Wolf | @var{filename} supports this) the backing file format is changed to |
312 | a616673d | Alex Bligh | @var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty |
313 | a616673d | Alex Bligh | string), then the image is rebased onto no backing file (i.e. it will exist |
314 | a616673d | Alex Bligh | independently of any backing file). |
315 | e6184690 | Kevin Wolf | |
316 | e6184690 | Kevin Wolf | There are two different modes in which @code{rebase} can operate: |
317 | e6184690 | Kevin Wolf | @table @option |
318 | e6184690 | Kevin Wolf | @item Safe mode |
319 | e6184690 | Kevin Wolf | This is the default mode and performs a real rebase operation. The new backing |
320 | e6184690 | Kevin Wolf | file may differ from the old one and qemu-img rebase will take care of keeping |
321 | e6184690 | Kevin Wolf | the guest-visible content of @var{filename} unchanged. |
322 | e6184690 | Kevin Wolf | |
323 | e6184690 | Kevin Wolf | In order to achieve this, any clusters that differ between @var{backing_file} |
324 | e6184690 | Kevin Wolf | and the old backing file of @var{filename} are merged into @var{filename} |
325 | e6184690 | Kevin Wolf | before actually changing the backing file. |
326 | e6184690 | Kevin Wolf | |
327 | e6184690 | Kevin Wolf | Note that the safe mode is an expensive operation, comparable to converting |
328 | e6184690 | Kevin Wolf | an image. It only works if the old backing file still exists. |
329 | e6184690 | Kevin Wolf | |
330 | e6184690 | Kevin Wolf | @item Unsafe mode |
331 | e6184690 | Kevin Wolf | qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the |
332 | e6184690 | Kevin Wolf | backing file name and format of @var{filename} is changed without any checks |
333 | e6184690 | Kevin Wolf | on the file contents. The user must take care of specifying the correct new |
334 | e6184690 | Kevin Wolf | backing file, or the guest-visible content of the image will be corrupted. |
335 | e6184690 | Kevin Wolf | |
336 | e6184690 | Kevin Wolf | This mode is useful for renaming or moving the backing file to somewhere else. |
337 | e6184690 | Kevin Wolf | It can be used without an accessible old backing file, i.e. you can use it to |
338 | e6184690 | Kevin Wolf | fix an image whose backing file has already been moved/renamed. |
339 | e6184690 | Kevin Wolf | @end table |
340 | e6184690 | Kevin Wolf | |
341 | 9fda6ab1 | Richard W.M. Jones | You can use @code{rebase} to perform a ``diff'' operation on two |
342 | 9fda6ab1 | Richard W.M. Jones | disk images. This can be useful when you have copied or cloned |
343 | 9fda6ab1 | Richard W.M. Jones | a guest, and you want to get back to a thin image on top of a |
344 | 9fda6ab1 | Richard W.M. Jones | template or base image. |
345 | 9fda6ab1 | Richard W.M. Jones | |
346 | 9fda6ab1 | Richard W.M. Jones | Say that @code{base.img} has been cloned as @code{modified.img} by |
347 | 9fda6ab1 | Richard W.M. Jones | copying it, and that the @code{modified.img} guest has run so there |
348 | 9fda6ab1 | Richard W.M. Jones | are now some changes compared to @code{base.img}. To construct a thin |
349 | 9fda6ab1 | Richard W.M. Jones | image called @code{diff.qcow2} that contains just the differences, do: |
350 | 9fda6ab1 | Richard W.M. Jones | |
351 | 9fda6ab1 | Richard W.M. Jones | @example |
352 | 9fda6ab1 | Richard W.M. Jones | qemu-img create -f qcow2 -b modified.img diff.qcow2 |
353 | 9fda6ab1 | Richard W.M. Jones | qemu-img rebase -b base.img diff.qcow2 |
354 | 9fda6ab1 | Richard W.M. Jones | @end example |
355 | 9fda6ab1 | Richard W.M. Jones | |
356 | 9fda6ab1 | Richard W.M. Jones | At this point, @code{modified.img} can be discarded, since |
357 | 9fda6ab1 | Richard W.M. Jones | @code{base.img + diff.qcow2} contains the same information. |
358 | 9fda6ab1 | Richard W.M. Jones | |
359 | ae6b0ed6 | Stefan Hajnoczi | @item resize @var{filename} [+ | -]@var{size} |
360 | ae6b0ed6 | Stefan Hajnoczi | |
361 | ae6b0ed6 | Stefan Hajnoczi | Change the disk image as if it had been created with @var{size}. |
362 | ae6b0ed6 | Stefan Hajnoczi | |
363 | ae6b0ed6 | Stefan Hajnoczi | Before using this command to shrink a disk image, you MUST use file system and |
364 | ae6b0ed6 | Stefan Hajnoczi | partitioning tools inside the VM to reduce allocated file systems and partition |
365 | ae6b0ed6 | Stefan Hajnoczi | sizes accordingly. Failure to do so will result in data loss! |
366 | ae6b0ed6 | Stefan Hajnoczi | |
367 | ae6b0ed6 | Stefan Hajnoczi | After using this command to grow a disk image, you must use file system and |
368 | ae6b0ed6 | Stefan Hajnoczi | partitioning tools inside the VM to actually begin using the new space on the |
369 | ae6b0ed6 | Stefan Hajnoczi | device. |
370 | 6f176b48 | Max Reitz | |
371 | 6f176b48 | Max Reitz | @item amend [-f @var{fmt}] -o @var{options} @var{filename} |
372 | 6f176b48 | Max Reitz | |
373 | 6f176b48 | Max Reitz | Amends the image format specific @var{options} for the image file |
374 | 6f176b48 | Max Reitz | @var{filename}. Not all file formats support this operation. |
375 | acd935ef | bellard | @end table |
376 | d3067b02 | Kevin Wolf | @c man end |
377 | acd935ef | bellard | |
378 | d3067b02 | Kevin Wolf | @ignore |
379 | d3067b02 | Kevin Wolf | @c man begin NOTES |
380 | f932c040 | Kevin Wolf | Supported image file formats: |
381 | f932c040 | Kevin Wolf | |
382 | f932c040 | Kevin Wolf | @table @option |
383 | f932c040 | Kevin Wolf | @item raw |
384 | f932c040 | Kevin Wolf | |
385 | f932c040 | Kevin Wolf | Raw disk image format (default). This format has the advantage of |
386 | f932c040 | Kevin Wolf | being simple and easily exportable to all other emulators. If your |
387 | f932c040 | Kevin Wolf | file system supports @emph{holes} (for example in ext2 or ext3 on |
388 | f932c040 | Kevin Wolf | Linux or NTFS on Windows), then only the written sectors will reserve |
389 | f932c040 | Kevin Wolf | space. Use @code{qemu-img info} to know the real size used by the |
390 | f932c040 | Kevin Wolf | image or @code{ls -ls} on Unix/Linux. |
391 | f932c040 | Kevin Wolf | |
392 | f932c040 | Kevin Wolf | @item qcow2 |
393 | f932c040 | Kevin Wolf | QEMU image format, the most versatile format. Use it to have smaller |
394 | f932c040 | Kevin Wolf | images (useful if your filesystem does not supports holes, for example |
395 | f932c040 | Kevin Wolf | on Windows), optional AES encryption, zlib based compression and |
396 | f932c040 | Kevin Wolf | support of multiple VM snapshots. |
397 | 8063d0fe | Kevin Wolf | |
398 | 3e032364 | Kevin Wolf | Supported options: |
399 | 3e032364 | Kevin Wolf | @table @code |
400 | d3067b02 | Kevin Wolf | @item compat |
401 | 7fa9e1f9 | Stefan Hajnoczi | Determines the qcow2 version to use. @code{compat=0.10} uses the |
402 | 7fa9e1f9 | Stefan Hajnoczi | traditional image format that can be read by any QEMU since 0.10. |
403 | d3067b02 | Kevin Wolf | @code{compat=1.1} enables image format extensions that only QEMU 1.1 and |
404 | 7fa9e1f9 | Stefan Hajnoczi | newer understand (this is the default). Amongst others, this includes zero |
405 | 7fa9e1f9 | Stefan Hajnoczi | clusters, which allow efficient copy-on-read for sparse images. |
406 | d3067b02 | Kevin Wolf | |
407 | 3e032364 | Kevin Wolf | @item backing_file |
408 | 3e032364 | Kevin Wolf | File name of a base image (see @option{create} subcommand) |
409 | 3e032364 | Kevin Wolf | @item backing_fmt |
410 | 3e032364 | Kevin Wolf | Image format of the base image |
411 | 3e032364 | Kevin Wolf | @item encryption |
412 | 136cd19d | Daniel P. Berrange | If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC. |
413 | 3e032364 | Kevin Wolf | |
414 | 136cd19d | Daniel P. Berrange | The use of encryption in qcow and qcow2 images is considered to be flawed by |
415 | 136cd19d | Daniel P. Berrange | modern cryptography standards, suffering from a number of design problems: |
416 | 136cd19d | Daniel P. Berrange | |
417 | 136cd19d | Daniel P. Berrange | @itemize @minus |
418 | 136cd19d | Daniel P. Berrange | @item The AES-CBC cipher is used with predictable initialization vectors based |
419 | 136cd19d | Daniel P. Berrange | on the sector number. This makes it vulnerable to chosen plaintext attacks |
420 | 136cd19d | Daniel P. Berrange | which can reveal the existence of encrypted data. |
421 | 136cd19d | Daniel P. Berrange | @item The user passphrase is directly used as the encryption key. A poorly |
422 | 136cd19d | Daniel P. Berrange | chosen or short passphrase will compromise the security of the encryption. |
423 | 136cd19d | Daniel P. Berrange | @item In the event of the passphrase being compromised there is no way to |
424 | 136cd19d | Daniel P. Berrange | change the passphrase to protect data in any qcow images. The files must |
425 | 136cd19d | Daniel P. Berrange | be cloned, using a different encryption passphrase in the new file. The |
426 | 136cd19d | Daniel P. Berrange | original file must then be securely erased using a program like shred, |
427 | 136cd19d | Daniel P. Berrange | though even this is ineffective with many modern storage technologies. |
428 | 136cd19d | Daniel P. Berrange | @end itemize |
429 | 136cd19d | Daniel P. Berrange | |
430 | 136cd19d | Daniel P. Berrange | Use of qcow / qcow2 encryption is thus strongly discouraged. Users are |
431 | 136cd19d | Daniel P. Berrange | recommended to use an alternative encryption technology such as the |
432 | 136cd19d | Daniel P. Berrange | Linux dm-crypt / LUKS system. |
433 | 3e032364 | Kevin Wolf | |
434 | 3e032364 | Kevin Wolf | @item cluster_size |
435 | 3e032364 | Kevin Wolf | Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster |
436 | 3e032364 | Kevin Wolf | sizes can improve the image file size whereas larger cluster sizes generally |
437 | 3e032364 | Kevin Wolf | provide better performance. |
438 | 3e032364 | Kevin Wolf | |
439 | 3e032364 | Kevin Wolf | @item preallocation |
440 | 3e032364 | Kevin Wolf | Preallocation mode (allowed values: off, metadata). An image with preallocated |
441 | 3e032364 | Kevin Wolf | metadata is initially larger but can improve performance when the image needs |
442 | 3e032364 | Kevin Wolf | to grow. |
443 | 3e032364 | Kevin Wolf | |
444 | d3067b02 | Kevin Wolf | @item lazy_refcounts |
445 | d3067b02 | Kevin Wolf | If this option is set to @code{on}, reference count updates are postponed with |
446 | d3067b02 | Kevin Wolf | the goal of avoiding metadata I/O and improving performance. This is |
447 | d3067b02 | Kevin Wolf | particularly interesting with @option{cache=writethrough} which doesn't batch |
448 | d3067b02 | Kevin Wolf | metadata updates. The tradeoff is that after a host crash, the reference count |
449 | d3067b02 | Kevin Wolf | tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img |
450 | d3067b02 | Kevin Wolf | check -r all} is required, which may take some time. |
451 | 3e032364 | Kevin Wolf | |
452 | d3067b02 | Kevin Wolf | This option can only be enabled if @code{compat=1.1} is specified. |
453 | f085800e | Stefan Hajnoczi | |
454 | f085800e | Stefan Hajnoczi | @end table |
455 | 3e032364 | Kevin Wolf | |
456 | d3067b02 | Kevin Wolf | @item Other |
457 | d3067b02 | Kevin Wolf | QEMU also supports various other image file formats for compatibility with |
458 | 8282db1b | Jeff Cody | older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), VHDX, |
459 | 8282db1b | Jeff Cody | qcow1 and QED. For a full list of supported formats see @code{qemu-img --help}. |
460 | d3067b02 | Kevin Wolf | For a more detailed description of these formats, see the QEMU Emulation User |
461 | d3067b02 | Kevin Wolf | Documentation. |
462 | 3e032364 | Kevin Wolf | |
463 | d3067b02 | Kevin Wolf | The main purpose of the block drivers for these formats is image conversion. |
464 | d3067b02 | Kevin Wolf | For running VMs, it is recommended to convert the disk images to either raw or |
465 | d3067b02 | Kevin Wolf | qcow2 in order to achieve good performance. |
466 | f932c040 | Kevin Wolf | @end table |
467 | f932c040 | Kevin Wolf | |
468 | f932c040 | Kevin Wolf | |
469 | acd935ef | bellard | @c man end |
470 | acd935ef | bellard | |
471 | acd935ef | bellard | @setfilename qemu-img |
472 | acd935ef | bellard | @settitle QEMU disk image utility |
473 | acd935ef | bellard | |
474 | acd935ef | bellard | @c man begin SEEALSO |
475 | acd935ef | bellard | The HTML documentation of QEMU for more precise information and Linux |
476 | acd935ef | bellard | user mode emulator invocation. |
477 | acd935ef | bellard | @c man end |
478 | acd935ef | bellard | |
479 | acd935ef | bellard | @c man begin AUTHOR |
480 | acd935ef | bellard | Fabrice Bellard |
481 | acd935ef | bellard | @c man end |
482 | acd935ef | bellard | |
483 | acd935ef | bellard | @end ignore |