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