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. |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 49 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 50 | |
| 51 | @item -c |
| 52 | indicates that target image must be compressed (qcow format only) |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 53 | @item -h |
| 54 | with or without a command shows help and lists the supported formats |
Jes Sorensen | aaf55b4 | 2011-07-19 15:01:34 +0200 | [diff] [blame] | 55 | @item -p |
| 56 | display progress bar (convert and rebase commands only) |
Kevin Wolf | a22f123 | 2011-08-26 15:27:13 +0200 | [diff] [blame] | 57 | @item -S @var{size} |
| 58 | indicates the consecutive number of bytes that must contain only zeros |
| 59 | for qemu-img to create a sparse image during conversion. This value is rounded |
| 60 | down to the nearest 512 bytes. You may use the common size suffixes like |
| 61 | @code{k} for kilobytes. |
Kevin Wolf | 3763f26 | 2011-12-07 13:57:13 +0100 | [diff] [blame] | 62 | @item -t @var{cache} |
| 63 | specifies the cache mode that should be used with the (destination) file. See |
| 64 | the documentation of the emulator's @code{-drive cache=...} option for allowed |
| 65 | values. |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 66 | @end table |
| 67 | |
| 68 | Parameters to snapshot subcommand: |
| 69 | |
| 70 | @table @option |
| 71 | |
| 72 | @item snapshot |
| 73 | is the name of the snapshot to create, apply or delete |
| 74 | @item -a |
| 75 | applies a snapshot (revert disk to saved state) |
| 76 | @item -c |
| 77 | creates a snapshot |
| 78 | @item -d |
| 79 | deletes a snapshot |
| 80 | @item -l |
| 81 | lists all snapshots in the given image |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 82 | @end table |
| 83 | |
| 84 | Command description: |
| 85 | |
| 86 | @table @option |
Federico Simoncelli | 8599ea4 | 2013-01-28 06:59:47 -0500 | [diff] [blame] | 87 | @item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] @var{filename} |
Kevin Wolf | e618469 | 2011-01-17 15:35:28 +0100 | [diff] [blame] | 88 | |
Federico Simoncelli | 8599ea4 | 2013-01-28 06:59:47 -0500 | [diff] [blame] | 89 | Perform a consistency check on the disk image @var{filename}. The command can |
| 90 | 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] | 91 | |
Kevin Wolf | 4534ff5 | 2012-05-11 16:07:02 +0200 | [diff] [blame] | 92 | If @code{-r} is specified, qemu-img tries to repair any inconsistencies found |
| 93 | during the check. @code{-r leaks} repairs only cluster leaks, whereas |
| 94 | @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] | 95 | wrong fix or hiding corruption that has already occurred. |
Kevin Wolf | 4534ff5 | 2012-05-11 16:07:02 +0200 | [diff] [blame] | 96 | |
Kevin Wolf | e618469 | 2011-01-17 15:35:28 +0100 | [diff] [blame] | 97 | Only the formats @code{qcow2}, @code{qed} and @code{vdi} support |
| 98 | consistency checks. |
| 99 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 100 | @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}] |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 101 | |
| 102 | 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] | 103 | @var{fmt}. Depending on the file format, you can add one or more @var{options} |
| 104 | that enable additional features of this format. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 105 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 106 | If the option @var{backing_file} is specified, then the image will record |
| 107 | only the differences from @var{backing_file}. No size needs to be specified in |
| 108 | this case. @var{backing_file} will never be modified unless you use the |
| 109 | @code{commit} monitor command (or qemu-img commit). |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 110 | |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 111 | The size can also be specified using the @var{size} option with @code{-o}, |
| 112 | it doesn't need to be specified separately in this case. |
| 113 | |
Kevin Wolf | 3763f26 | 2011-12-07 13:57:13 +0100 | [diff] [blame] | 114 | @item commit [-f @var{fmt}] [-t @var{cache}] @var{filename} |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 115 | |
| 116 | Commit the changes recorded in @var{filename} in its base image. |
| 117 | |
Kevin Wolf | 3763f26 | 2011-12-07 13:57:13 +0100 | [diff] [blame] | 118 | @item convert [-c] [-p] [-f @var{fmt}] [-t @var{cache}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_name}] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename} |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 119 | |
edison | 51ef672 | 2010-09-21 19:58:41 -0700 | [diff] [blame] | 120 | Convert the disk image @var{filename} or a snapshot @var{snapshot_name} to disk image @var{output_filename} |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 121 | using format @var{output_fmt}. It can be optionally compressed (@code{-c} |
| 122 | option) or use any format specific options like encryption (@code{-o} option). |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 123 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 124 | Only the formats @code{qcow} and @code{qcow2} support compression. The |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 125 | compression is read-only. It means that if a compressed sector is |
| 126 | rewritten, then it is rewritten as uncompressed data. |
| 127 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 128 | Image conversion is also useful to get smaller image when using a |
| 129 | growable format such as @code{qcow} or @code{cow}: the empty sectors |
| 130 | are detected and suppressed from the destination image. |
| 131 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 132 | You can use the @var{backing_file} option to force the output image to be |
| 133 | created as a copy on write image of the specified base image; the |
| 134 | @var{backing_file} should have the same content as the input's base image, |
| 135 | however the path, image format, etc may differ. |
| 136 | |
Kashyap Chamarthy | e535756 | 2012-10-18 11:25:34 +0530 | [diff] [blame] | 137 | @item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename} |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 138 | |
| 139 | Give information about the disk image @var{filename}. Use it in |
| 140 | particular to know the size reserved on disk which can be different |
bellard | 19d3679 | 2006-08-07 21:34:34 +0000 | [diff] [blame] | 141 | 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] | 142 | they are displayed too. The command can output in the format @var{ofmt} |
| 143 | which is either @code{human} or @code{json}. |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 144 | |
Kashyap Chamarthy | e535756 | 2012-10-18 11:25:34 +0530 | [diff] [blame] | 145 | If a disk image has a backing file chain, information about each disk image in |
| 146 | the chain can be recursively enumerated by using the option @code{--backing-chain}. |
| 147 | |
| 148 | For instance, if you have an image chain like: |
| 149 | |
| 150 | @example |
| 151 | base.qcow2 <- snap1.qcow2 <- snap2.qcow2 |
| 152 | @end example |
| 153 | |
| 154 | To enumerate information about each disk image in the above chain, starting from top to base, do: |
| 155 | |
| 156 | @example |
| 157 | qemu-img info --backing-chain snap2.qcow2 |
| 158 | @end example |
| 159 | |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 160 | @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename} |
| 161 | |
| 162 | List, apply, create or delete snapshots in image @var{filename}. |
Stefan Hajnoczi | ae6b0ed | 2010-04-24 09:12:12 +0100 | [diff] [blame] | 163 | |
Kevin Wolf | 3763f26 | 2011-12-07 13:57:13 +0100 | [diff] [blame] | 164 | @item rebase [-f @var{fmt}] [-t @var{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] | 165 | |
| 166 | Changes the backing file of an image. Only the formats @code{qcow2} and |
| 167 | @code{qed} support changing the backing file. |
| 168 | |
| 169 | The backing file is changed to @var{backing_file} and (if the image format of |
| 170 | @var{filename} supports this) the backing file format is changed to |
Alex Bligh | a616673 | 2012-10-16 13:46:18 +0100 | [diff] [blame] | 171 | @var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty |
| 172 | string), then the image is rebased onto no backing file (i.e. it will exist |
| 173 | independently of any backing file). |
Kevin Wolf | e618469 | 2011-01-17 15:35:28 +0100 | [diff] [blame] | 174 | |
| 175 | There are two different modes in which @code{rebase} can operate: |
| 176 | @table @option |
| 177 | @item Safe mode |
| 178 | This is the default mode and performs a real rebase operation. The new backing |
| 179 | file may differ from the old one and qemu-img rebase will take care of keeping |
| 180 | the guest-visible content of @var{filename} unchanged. |
| 181 | |
| 182 | In order to achieve this, any clusters that differ between @var{backing_file} |
| 183 | and the old backing file of @var{filename} are merged into @var{filename} |
| 184 | before actually changing the backing file. |
| 185 | |
| 186 | Note that the safe mode is an expensive operation, comparable to converting |
| 187 | an image. It only works if the old backing file still exists. |
| 188 | |
| 189 | @item Unsafe mode |
| 190 | qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the |
| 191 | backing file name and format of @var{filename} is changed without any checks |
| 192 | on the file contents. The user must take care of specifying the correct new |
| 193 | backing file, or the guest-visible content of the image will be corrupted. |
| 194 | |
| 195 | This mode is useful for renaming or moving the backing file to somewhere else. |
| 196 | It can be used without an accessible old backing file, i.e. you can use it to |
| 197 | fix an image whose backing file has already been moved/renamed. |
| 198 | @end table |
| 199 | |
Richard W.M. Jones | 9fda6ab | 2012-05-21 14:58:05 +0100 | [diff] [blame] | 200 | You can use @code{rebase} to perform a ``diff'' operation on two |
| 201 | disk images. This can be useful when you have copied or cloned |
| 202 | a guest, and you want to get back to a thin image on top of a |
| 203 | template or base image. |
| 204 | |
| 205 | Say that @code{base.img} has been cloned as @code{modified.img} by |
| 206 | copying it, and that the @code{modified.img} guest has run so there |
| 207 | are now some changes compared to @code{base.img}. To construct a thin |
| 208 | image called @code{diff.qcow2} that contains just the differences, do: |
| 209 | |
| 210 | @example |
| 211 | qemu-img create -f qcow2 -b modified.img diff.qcow2 |
| 212 | qemu-img rebase -b base.img diff.qcow2 |
| 213 | @end example |
| 214 | |
| 215 | At this point, @code{modified.img} can be discarded, since |
| 216 | @code{base.img + diff.qcow2} contains the same information. |
| 217 | |
Stefan Hajnoczi | ae6b0ed | 2010-04-24 09:12:12 +0100 | [diff] [blame] | 218 | @item resize @var{filename} [+ | -]@var{size} |
| 219 | |
| 220 | Change the disk image as if it had been created with @var{size}. |
| 221 | |
| 222 | Before using this command to shrink a disk image, you MUST use file system and |
| 223 | partitioning tools inside the VM to reduce allocated file systems and partition |
| 224 | sizes accordingly. Failure to do so will result in data loss! |
| 225 | |
| 226 | After using this command to grow a disk image, you must use file system and |
| 227 | partitioning tools inside the VM to actually begin using the new space on the |
| 228 | device. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 229 | @end table |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 230 | @c man end |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 231 | |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 232 | @ignore |
| 233 | @c man begin NOTES |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 234 | Supported image file formats: |
| 235 | |
| 236 | @table @option |
| 237 | @item raw |
| 238 | |
| 239 | Raw disk image format (default). This format has the advantage of |
| 240 | being simple and easily exportable to all other emulators. If your |
| 241 | file system supports @emph{holes} (for example in ext2 or ext3 on |
| 242 | Linux or NTFS on Windows), then only the written sectors will reserve |
| 243 | space. Use @code{qemu-img info} to know the real size used by the |
| 244 | image or @code{ls -ls} on Unix/Linux. |
| 245 | |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 246 | @item qcow2 |
| 247 | QEMU image format, the most versatile format. Use it to have smaller |
| 248 | images (useful if your filesystem does not supports holes, for example |
| 249 | on Windows), optional AES encryption, zlib based compression and |
| 250 | support of multiple VM snapshots. |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 251 | |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 252 | Supported options: |
| 253 | @table @code |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 254 | @item compat |
| 255 | Determines the qcow2 version to use. @code{compat=0.10} uses the traditional |
| 256 | image format that can be read by any QEMU since 0.10 (this is the default). |
| 257 | @code{compat=1.1} enables image format extensions that only QEMU 1.1 and |
| 258 | newer understand. Amongst others, this includes zero clusters, which allow |
| 259 | efficient copy-on-read for sparse images. |
| 260 | |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 261 | @item backing_file |
| 262 | File name of a base image (see @option{create} subcommand) |
| 263 | @item backing_fmt |
| 264 | Image format of the base image |
| 265 | @item encryption |
| 266 | If this option is set to @code{on}, the image is encrypted. |
| 267 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 268 | Encryption uses the AES format which is very secure (128 bit keys). Use |
| 269 | a long password (16 characters) to get maximum protection. |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 270 | |
| 271 | @item cluster_size |
| 272 | Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster |
| 273 | sizes can improve the image file size whereas larger cluster sizes generally |
| 274 | provide better performance. |
| 275 | |
| 276 | @item preallocation |
| 277 | Preallocation mode (allowed values: off, metadata). An image with preallocated |
| 278 | metadata is initially larger but can improve performance when the image needs |
| 279 | to grow. |
| 280 | |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 281 | @item lazy_refcounts |
| 282 | If this option is set to @code{on}, reference count updates are postponed with |
| 283 | the goal of avoiding metadata I/O and improving performance. This is |
| 284 | particularly interesting with @option{cache=writethrough} which doesn't batch |
| 285 | metadata updates. The tradeoff is that after a host crash, the reference count |
| 286 | tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img |
| 287 | check -r all} is required, which may take some time. |
| 288 | |
| 289 | This option can only be enabled if @code{compat=1.1} is specified. |
| 290 | |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 291 | @end table |
| 292 | |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 293 | @item Other |
| 294 | QEMU also supports various other image file formats for compatibility with |
| 295 | older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), qcow1 |
| 296 | and QED. For a full list of supported formats see @code{qemu-img --help}. |
| 297 | For a more detailed description of these formats, see the QEMU Emulation User |
| 298 | Documentation. |
Stefan Hajnoczi | f085800 | 2012-06-13 14:29:15 +0100 | [diff] [blame] | 299 | |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 300 | The main purpose of the block drivers for these formats is image conversion. |
| 301 | For running VMs, it is recommended to convert the disk images to either raw or |
| 302 | qcow2 in order to achieve good performance. |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 303 | @end table |
| 304 | |
| 305 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 306 | @c man end |
| 307 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 308 | @setfilename qemu-img |
| 309 | @settitle QEMU disk image utility |
| 310 | |
| 311 | @c man begin SEEALSO |
| 312 | The HTML documentation of QEMU for more precise information and Linux |
| 313 | user mode emulator invocation. |
| 314 | @c man end |
| 315 | |
| 316 | @c man begin AUTHOR |
| 317 | Fabrice Bellard |
| 318 | @c man end |
| 319 | |
| 320 | @end ignore |