bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 1 | @example |
| 2 | @c man begin SYNOPSIS |
Denis V. Lunev | 1098513 | 2016-06-17 17:44:13 +0300 | [diff] [blame] | 3 | @command{qemu-img} [@var{standard} @var{options}] @var{command} [@var{command} @var{options}] |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 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 | |
Denis V. Lunev | 1098513 | 2016-06-17 17:44:13 +0300 | [diff] [blame] | 19 | Standard options: |
| 20 | @table @option |
| 21 | @item -h, --help |
| 22 | Display this help and exit |
| 23 | @item -V, --version |
| 24 | Display version information and exit |
Denis V. Lunev | 06a1e0c | 2016-06-17 17:44:14 +0300 | [diff] [blame] | 25 | @item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] |
| 26 | @findex --trace |
| 27 | @include qemu-option-trace.texi |
Denis V. Lunev | 1098513 | 2016-06-17 17:44:13 +0300 | [diff] [blame] | 28 | @end table |
| 29 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 30 | The following commands are supported: |
Stuart Brady | 153859b | 2009-06-07 00:42:17 +0100 | [diff] [blame] | 31 | |
| 32 | @include qemu-img-cmds.texi |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 33 | |
| 34 | Command parameters: |
| 35 | @table @var |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 36 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 37 | @item filename |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 38 | is a disk image filename |
Daniel P. Berrange | eb769f7 | 2016-02-17 10:10:20 +0000 | [diff] [blame] | 39 | |
ths | 5fafdf2 | 2007-09-16 21:08:06 +0000 | [diff] [blame] | 40 | @item fmt |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 41 | is the disk image format. It is guessed automatically in most cases. See below |
| 42 | for a description of the supported disk formats. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 43 | |
ths | 5fafdf2 | 2007-09-16 21:08:06 +0000 | [diff] [blame] | 44 | @item size |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 45 | is the disk image size in bytes. Optional suffixes @code{k} or @code{K} |
| 46 | (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M) |
| 47 | and T (terabyte, 1024G) are supported. @code{b} is ignored. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 48 | |
| 49 | @item output_filename |
ths | 5fafdf2 | 2007-09-16 21:08:06 +0000 | [diff] [blame] | 50 | is the destination disk image filename |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 51 | |
| 52 | @item output_fmt |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 53 | is the destination format |
| 54 | |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 55 | @item options |
| 56 | is a comma separated list of format specific options in a |
| 57 | 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] | 58 | by the used format or see the format descriptions below for details. |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 59 | |
Wenchao Xia | ef80654 | 2013-12-04 17:10:57 +0800 | [diff] [blame] | 60 | @item snapshot_param |
| 61 | is param used for internal snapshot, format is |
| 62 | 'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]' |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 63 | |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 64 | @end table |
| 65 | |
| 66 | @table @option |
| 67 | |
| 68 | @item --object @var{objectdef} |
| 69 | is a QEMU user creatable object definition. See the @code{qemu(1)} manual |
| 70 | page for a description of the object properties. The most common object |
| 71 | type is a @code{secret}, which is used to supply passwords and/or encryption |
| 72 | keys. |
| 73 | |
| 74 | @item --image-opts |
| 75 | Indicates that the source @var{filename} parameter is to be interpreted as a |
| 76 | full option string, not a plain filename. This parameter is mutually |
| 77 | exclusive with the @var{-f} parameter. |
| 78 | |
| 79 | @item --target-image-opts |
| 80 | Indicates that the @var{output_filename} parameter(s) are to be interpreted as |
| 81 | a full option string, not a plain filename. This parameter is mutually |
| 82 | exclusive with the @var{-O} parameters. It is currently required to also use |
| 83 | the @var{-n} parameter to skip image creation. This restriction may be relaxed |
| 84 | in a future release. |
| 85 | |
Fam Zheng | a7e326d | 2018-02-09 13:29:14 +0800 | [diff] [blame] | 86 | @item --force-share (-U) |
| 87 | If specified, @code{qemu-img} will open the image in shared mode, allowing |
| 88 | other QEMU processes to open it in write mode. For example, this can be used to |
| 89 | get the image information (with 'info' subcommand) when the image is used by a |
| 90 | running guest. Note that this could produce inconsistent results because of |
| 91 | concurrent metadata changes, etc. This option is only allowed when opening |
| 92 | images in read-only mode. |
| 93 | |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 94 | @item --backing-chain |
| 95 | will enumerate information about backing files in a disk image chain. Refer |
| 96 | below for further description. |
| 97 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 98 | @item -c |
Fam Zheng | b855043 | 2018-07-27 11:34:00 +0800 | [diff] [blame] | 99 | indicates that target image must be compressed (qcow format only) |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 100 | |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 101 | @item -h |
| 102 | with or without a command shows help and lists the supported formats |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 103 | |
Jes Sorensen | aaf55b4 | 2011-07-19 15:01:34 +0200 | [diff] [blame] | 104 | @item -p |
Kevin Wolf | 0e3bd99 | 2014-01-20 15:12:16 +0100 | [diff] [blame] | 105 | display progress bar (compare, convert and rebase commands only). |
| 106 | If the @var{-p} option is not used for a command that supports it, the |
Max Reitz | 262fbae | 2017-02-08 00:57:57 +0100 | [diff] [blame] | 107 | progress is reported when the process receives a @code{SIGUSR1} or |
| 108 | @code{SIGINFO} signal. |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 109 | |
Miroslav Rezanina | f382d43 | 2013-02-13 09:09:40 +0100 | [diff] [blame] | 110 | @item -q |
| 111 | Quiet mode - do not print any output (except errors). There's no progress bar |
| 112 | in case both @var{-q} and @var{-p} options are used. |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 113 | |
Kevin Wolf | a22f123 | 2011-08-26 15:27:13 +0200 | [diff] [blame] | 114 | @item -S @var{size} |
| 115 | indicates the consecutive number of bytes that must contain only zeros |
| 116 | for qemu-img to create a sparse image during conversion. This value is rounded |
| 117 | down to the nearest 512 bytes. You may use the common size suffixes like |
Fam Zheng | b855043 | 2018-07-27 11:34:00 +0800 | [diff] [blame] | 118 | @code{k} for kilobytes. |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 119 | |
Kevin Wolf | 3763f26 | 2011-12-07 13:57:13 +0100 | [diff] [blame] | 120 | @item -t @var{cache} |
| 121 | specifies the cache mode that should be used with the (destination) file. See |
| 122 | the documentation of the emulator's @code{-drive cache=...} option for allowed |
| 123 | values. |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 124 | |
Max Reitz | 4005595 | 2014-07-22 22:58:42 +0200 | [diff] [blame] | 125 | @item -T @var{src_cache} |
Stefan Hajnoczi | bb87fdf | 2014-09-02 11:01:02 +0100 | [diff] [blame] | 126 | specifies the cache mode that should be used with the source file(s). See |
| 127 | the documentation of the emulator's @code{-drive cache=...} option for allowed |
| 128 | values. |
Fam Zheng | c150eb9 | 2018-02-09 13:29:13 +0800 | [diff] [blame] | 129 | |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 130 | @end table |
| 131 | |
| 132 | Parameters to snapshot subcommand: |
| 133 | |
| 134 | @table @option |
| 135 | |
| 136 | @item snapshot |
| 137 | is the name of the snapshot to create, apply or delete |
| 138 | @item -a |
| 139 | applies a snapshot (revert disk to saved state) |
| 140 | @item -c |
| 141 | creates a snapshot |
| 142 | @item -d |
| 143 | deletes a snapshot |
| 144 | @item -l |
| 145 | lists all snapshots in the given image |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 146 | @end table |
| 147 | |
Miroslav Rezanina | d14ed18 | 2013-02-13 09:09:41 +0100 | [diff] [blame] | 148 | Parameters to compare subcommand: |
| 149 | |
| 150 | @table @option |
| 151 | |
| 152 | @item -f |
| 153 | First image format |
| 154 | @item -F |
| 155 | Second image format |
| 156 | @item -s |
Daniel P. Berrange | b6af097 | 2015-08-26 12:17:13 +0100 | [diff] [blame] | 157 | Strict mode - fail on different image size or sector allocation |
Miroslav Rezanina | d14ed18 | 2013-02-13 09:09:41 +0100 | [diff] [blame] | 158 | @end table |
| 159 | |
Alexandre Derumier | b2e1049 | 2013-09-02 19:07:24 +0100 | [diff] [blame] | 160 | Parameters to convert subcommand: |
| 161 | |
| 162 | @table @option |
| 163 | |
| 164 | @item -n |
| 165 | Skip the creation of the target volume |
Peter Lieven | 2d9187b | 2017-02-28 13:40:07 +0100 | [diff] [blame] | 166 | @item -m |
| 167 | Number of parallel coroutines for the convert process |
| 168 | @item -W |
| 169 | Allow out-of-order writes to the destination. This option improves performance, |
| 170 | but is only recommended for preallocated devices like host devices or other |
| 171 | raw block devices. |
Fam Zheng | e11ce12 | 2018-07-27 11:34:01 +0800 | [diff] [blame] | 172 | @item -C |
| 173 | Try to use copy offloading to move data from source image to target. This may |
| 174 | improve performance if the data is remote, such as with NFS or iSCSI backends, |
| 175 | but will not automatically sparsify zero sectors, and may result in a fully |
| 176 | allocated target image depending on the host support for getting allocation |
| 177 | information. |
Max Reitz | 8eaac02 | 2019-05-07 22:35:03 +0200 | [diff] [blame] | 178 | @item --salvage |
| 179 | Try to ignore I/O errors when reading. Unless in quiet mode (@code{-q}), errors |
| 180 | will still be printed. Areas that cannot be read from the source will be |
| 181 | treated as containing only zeroes. |
Alexandre Derumier | b2e1049 | 2013-09-02 19:07:24 +0100 | [diff] [blame] | 182 | @end table |
| 183 | |
Reda Sallahi | 86ce1f6 | 2016-08-10 04:43:12 +0200 | [diff] [blame] | 184 | Parameters to dd subcommand: |
| 185 | |
| 186 | @table @option |
| 187 | |
| 188 | @item bs=@var{block_size} |
| 189 | defines the block size |
| 190 | @item count=@var{blocks} |
| 191 | sets the number of input blocks to copy |
| 192 | @item if=@var{input} |
| 193 | sets the input file |
| 194 | @item of=@var{output} |
| 195 | sets the output file |
Reda Sallahi | f7c1553 | 2016-08-10 16:16:09 +0200 | [diff] [blame] | 196 | @item skip=@var{blocks} |
| 197 | sets the number of input blocks to skip |
Reda Sallahi | 86ce1f6 | 2016-08-10 04:43:12 +0200 | [diff] [blame] | 198 | @end table |
| 199 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 200 | Command description: |
| 201 | |
| 202 | @table @option |
John Snow | 83e6da0 | 2018-05-03 18:56:45 -0400 | [diff] [blame] | 203 | |
John Snow | 13c24ed | 2019-04-09 17:06:55 -0400 | [diff] [blame] | 204 | @item amend [--object @var{objectdef}] [--image-opts] [-p] [-q] [-f @var{fmt}] [-t @var{cache}] -o @var{options} @var{filename} |
John Snow | 83e6da0 | 2018-05-03 18:56:45 -0400 | [diff] [blame] | 205 | |
| 206 | Amends the image format specific @var{options} for the image file |
| 207 | @var{filename}. Not all file formats support this operation. |
| 208 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 209 | @item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] [-U] @var{filename} |
Kevin Wolf | b6133b8 | 2014-08-05 14:17:13 +0200 | [diff] [blame] | 210 | |
Kevin Wolf | b6495fa | 2015-07-10 18:09:18 +0200 | [diff] [blame] | 211 | Run a simple sequential I/O benchmark on the specified image. If @code{-w} is |
| 212 | specified, a write test is performed, otherwise a read test is performed. |
| 213 | |
| 214 | A total number of @var{count} I/O requests is performed, each @var{buffer_size} |
Kevin Wolf | d3199a3 | 2015-07-10 18:09:18 +0200 | [diff] [blame] | 215 | bytes in size, and with @var{depth} requests in parallel. The first request |
Kevin Wolf | 83de9be | 2015-07-13 13:13:17 +0200 | [diff] [blame] | 216 | starts at the position given by @var{offset}, each following request increases |
| 217 | the current position by @var{step_size}. If @var{step_size} is not given, |
| 218 | @var{buffer_size} is used for its value. |
Kevin Wolf | b6133b8 | 2014-08-05 14:17:13 +0200 | [diff] [blame] | 219 | |
Kevin Wolf | 55d539c | 2016-06-03 13:59:41 +0200 | [diff] [blame] | 220 | If @var{flush_interval} is specified for a write test, the request queue is |
| 221 | drained and a flush is issued before new writes are made whenever the number of |
| 222 | remaining requests is a multiple of @var{flush_interval}. If additionally |
| 223 | @code{--no-drain} is specified, a flush is issued without draining the request |
| 224 | queue first. |
| 225 | |
Kevin Wolf | b6133b8 | 2014-08-05 14:17:13 +0200 | [diff] [blame] | 226 | If @code{-n} is specified, the native AIO backend is used if possible. On |
| 227 | Linux, this option only works if @code{-t none} or @code{-t directsync} is |
| 228 | specified as well. |
| 229 | |
Kevin Wolf | b6495fa | 2015-07-10 18:09:18 +0200 | [diff] [blame] | 230 | For write tests, by default a buffer filled with zeros is written. This can be |
| 231 | overridden with a pattern byte specified by @var{pattern}. |
| 232 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 233 | @item check [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] [-U] @var{filename} |
Kevin Wolf | e618469 | 2011-01-17 15:35:28 +0100 | [diff] [blame] | 234 | |
Federico Simoncelli | 8599ea4 | 2013-01-28 06:59:47 -0500 | [diff] [blame] | 235 | Perform a consistency check on the disk image @var{filename}. The command can |
| 236 | output in the format @var{ofmt} which is either @code{human} or @code{json}. |
Max Reitz | 987402c | 2019-05-15 09:59:16 +0200 | [diff] [blame] | 237 | The JSON output is an object of QAPI type @code{ImageCheck}. |
Kevin Wolf | e618469 | 2011-01-17 15:35:28 +0100 | [diff] [blame] | 238 | |
Kevin Wolf | 4534ff5 | 2012-05-11 16:07:02 +0200 | [diff] [blame] | 239 | If @code{-r} is specified, qemu-img tries to repair any inconsistencies found |
| 240 | during the check. @code{-r leaks} repairs only cluster leaks, whereas |
| 241 | @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] | 242 | wrong fix or hiding corruption that has already occurred. |
Kevin Wolf | 4534ff5 | 2012-05-11 16:07:02 +0200 | [diff] [blame] | 243 | |
Kevin Wolf | e618469 | 2011-01-17 15:35:28 +0100 | [diff] [blame] | 244 | Only the formats @code{qcow2}, @code{qed} and @code{vdi} support |
| 245 | consistency checks. |
| 246 | |
Max Reitz | d6635c4 | 2014-06-02 22:15:21 +0200 | [diff] [blame] | 247 | In case the image does not have any inconsistencies, check exits with @code{0}. |
| 248 | Other exit codes indicate the kind of inconsistency found or if another error |
| 249 | occurred. The following table summarizes all exit codes of the check subcommand: |
| 250 | |
| 251 | @table @option |
| 252 | |
| 253 | @item 0 |
| 254 | Check completed, the image is (now) consistent |
| 255 | @item 1 |
| 256 | Check not completed because of internal errors |
| 257 | @item 2 |
| 258 | Check completed, image is corrupted |
| 259 | @item 3 |
| 260 | Check completed, image has leaked clusters, but is not corrupted |
| 261 | @item 63 |
| 262 | Checks are not supported by the image format |
| 263 | |
| 264 | @end table |
| 265 | |
| 266 | If @code{-r} is specified, exit codes representing the image state refer to the |
| 267 | state after (the attempt at) repairing it. That is, a successful @code{-r all} |
| 268 | will yield the exit code 0, independently of the image state before. |
| 269 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 270 | @item commit [--object @var{objectdef}] [--image-opts] [-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] | 271 | |
Jeff Cody | 3722290 | 2014-01-24 09:02:37 -0500 | [diff] [blame] | 272 | Commit the changes recorded in @var{filename} in its base image or backing file. |
| 273 | If the backing file is smaller than the snapshot, then the backing file will be |
| 274 | resized to be the same size as the snapshot. If the snapshot is smaller than |
| 275 | the backing file, the backing file will not be truncated. If you want the |
| 276 | backing file to match the size of the smaller snapshot, you can safely truncate |
| 277 | it yourself once the commit operation successfully completes. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 278 | |
Max Reitz | 9a86fe4 | 2014-10-24 15:57:38 +0200 | [diff] [blame] | 279 | The image @var{filename} is emptied after the operation has succeeded. If you do |
| 280 | not need @var{filename} afterwards and intend to drop it, you may skip emptying |
| 281 | @var{filename} by specifying the @code{-d} flag. |
| 282 | |
Max Reitz | 1b22bff | 2014-10-24 15:57:40 +0200 | [diff] [blame] | 283 | If the backing chain of the given image file @var{filename} has more than one |
| 284 | layer, the backing file into which the changes will be committed may be |
| 285 | specified as @var{base} (which has to be part of @var{filename}'s backing |
| 286 | chain). If @var{base} is not specified, the immediate backing file of the top |
Max Reitz | 67e5647 | 2017-10-26 09:59:47 +0200 | [diff] [blame] | 287 | image (which is @var{filename}) will be used. Note that after a commit operation |
| 288 | all images between @var{base} and the top image will be invalid and may return |
| 289 | garbage data when read. For this reason, @code{-b} implies @code{-d} (so that |
| 290 | the top image stays valid). |
Max Reitz | 1b22bff | 2014-10-24 15:57:40 +0200 | [diff] [blame] | 291 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 292 | @item compare [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-F @var{fmt}] [-T @var{src_cache}] [-p] [-q] [-s] [-U] @var{filename1} @var{filename2} |
Miroslav Rezanina | d14ed18 | 2013-02-13 09:09:41 +0100 | [diff] [blame] | 293 | |
| 294 | Check if two images have the same content. You can compare images with |
| 295 | different format or settings. |
| 296 | |
| 297 | The format is probed unless you specify it by @var{-f} (used for |
| 298 | @var{filename1}) and/or @var{-F} (used for @var{filename2}) option. |
| 299 | |
| 300 | By default, images with different size are considered identical if the larger |
| 301 | image contains only unallocated and/or zeroed sectors in the area after the end |
| 302 | of the other image. In addition, if any sector is not allocated in one image |
| 303 | and contains only zero bytes in the second one, it is evaluated as equal. You |
| 304 | can use Strict mode by specifying the @var{-s} option. When compare runs in |
| 305 | Strict mode, it fails in case image size differs or a sector is allocated in |
| 306 | one image and is not allocated in the second one. |
| 307 | |
| 308 | By default, compare prints out a result message. This message displays |
| 309 | information that both images are same or the position of the first different |
| 310 | byte. In addition, result message can report different image size in case |
| 311 | Strict mode is used. |
| 312 | |
| 313 | Compare exits with @code{0} in case the images are equal and with @code{1} |
| 314 | in case the images differ. Other exit codes mean an error occurred during |
| 315 | execution and standard error output should contain an error message. |
| 316 | The following table sumarizes all exit codes of the compare subcommand: |
| 317 | |
| 318 | @table @option |
| 319 | |
| 320 | @item 0 |
| 321 | Images are identical |
| 322 | @item 1 |
| 323 | Images differ |
| 324 | @item 2 |
| 325 | Error on opening an image |
| 326 | @item 3 |
| 327 | Error on checking a sector allocation |
| 328 | @item 4 |
| 329 | Error on reading data |
| 330 | |
| 331 | @end table |
| 332 | |
Fam Zheng | e11ce12 | 2018-07-27 11:34:01 +0800 | [diff] [blame] | 333 | @item convert [--object @var{objectdef}] [--image-opts] [--target-image-opts] [-U] [-C] [-c] [-p] [-q] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}] [-W] @var{filename} [@var{filename2} [...]] @var{output_filename} |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 334 | |
Thomas Huth | 46e8d27 | 2018-06-06 14:35:51 +0200 | [diff] [blame] | 335 | Convert the disk image @var{filename} or a snapshot @var{snapshot_param} |
Wenchao Xia | ef80654 | 2013-12-04 17:10:57 +0800 | [diff] [blame] | 336 | 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] | 337 | option) or use any format specific options like encryption (@code{-o} option). |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 338 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 339 | Only the formats @code{qcow} and @code{qcow2} support compression. The |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 340 | compression is read-only. It means that if a compressed sector is |
| 341 | rewritten, then it is rewritten as uncompressed data. |
| 342 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 343 | Image conversion is also useful to get smaller image when using a |
Stefan Hajnoczi | 550830f | 2014-09-16 15:24:24 +0100 | [diff] [blame] | 344 | growable format such as @code{qcow}: the empty sectors are detected and |
| 345 | suppressed from the destination image. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 346 | |
Peter Lieven | 11b6699 | 2013-10-24 12:07:05 +0200 | [diff] [blame] | 347 | @var{sparse_size} indicates the consecutive number of bytes (defaults to 4k) |
| 348 | that must contain only zeros for qemu-img to create a sparse image during |
| 349 | conversion. If @var{sparse_size} is 0, the source will not be scanned for |
| 350 | unallocated or zero sectors, and the destination image will always be |
| 351 | fully allocated. |
| 352 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 353 | You can use the @var{backing_file} option to force the output image to be |
| 354 | created as a copy on write image of the specified base image; the |
| 355 | @var{backing_file} should have the same content as the input's base image, |
| 356 | however the path, image format, etc may differ. |
| 357 | |
Fam Zheng | a16efd5 | 2017-08-04 22:36:58 +0800 | [diff] [blame] | 358 | If a relative path name is given, the backing file is looked up relative to |
| 359 | the directory containing @var{output_filename}. |
| 360 | |
Alexandre Derumier | b2e1049 | 2013-09-02 19:07:24 +0100 | [diff] [blame] | 361 | If the @code{-n} option is specified, the target volume creation will be |
| 362 | skipped. This is useful for formats such as @code{rbd} if the target |
| 363 | volume has already been created with site specific options that cannot |
| 364 | be supplied through qemu-img. |
| 365 | |
Peter Lieven | 2d9187b | 2017-02-28 13:40:07 +0100 | [diff] [blame] | 366 | Out of order writes can be enabled with @code{-W} to improve performance. |
| 367 | This is only recommended for preallocated devices like host devices or other |
| 368 | raw block devices. Out of order write does not work in combination with |
| 369 | creating compressed images. |
| 370 | |
| 371 | @var{num_coroutines} specifies how many coroutines work in parallel during |
| 372 | the convert process (defaults to 8). |
| 373 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 374 | @item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}] |
John Snow | 83e6da0 | 2018-05-03 18:56:45 -0400 | [diff] [blame] | 375 | |
| 376 | Create the new disk image @var{filename} of size @var{size} and format |
| 377 | @var{fmt}. Depending on the file format, you can add one or more @var{options} |
| 378 | that enable additional features of this format. |
| 379 | |
| 380 | If the option @var{backing_file} is specified, then the image will record |
| 381 | only the differences from @var{backing_file}. No size needs to be specified in |
| 382 | this case. @var{backing_file} will never be modified unless you use the |
| 383 | @code{commit} monitor command (or qemu-img commit). |
| 384 | |
| 385 | If a relative path name is given, the backing file is looked up relative to |
| 386 | the directory containing @var{filename}. |
| 387 | |
| 388 | Note that a given backing file will be opened to check that it is valid. Use |
| 389 | the @code{-u} option to enable unsafe backing file mode, which means that the |
| 390 | image will be created even if the associated backing file cannot be opened. A |
| 391 | matching backing file must be created or additional options be used to make the |
| 392 | backing file specification valid when you want to use an image created this |
| 393 | way. |
| 394 | |
| 395 | The size can also be specified using the @var{size} option with @code{-o}, |
| 396 | it doesn't need to be specified separately in this case. |
| 397 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 398 | @item dd [--image-opts] [-U] [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output} |
Reda Sallahi | 86ce1f6 | 2016-08-10 04:43:12 +0200 | [diff] [blame] | 399 | |
| 400 | Dd copies from @var{input} file to @var{output} file converting it from |
| 401 | @var{fmt} format to @var{output_fmt} format. |
| 402 | |
| 403 | The data is by default read and written using blocks of 512 bytes but can be |
| 404 | modified by specifying @var{block_size}. If count=@var{blocks} is specified |
| 405 | dd will stop reading input after reading @var{blocks} input blocks. |
| 406 | |
| 407 | The size syntax is similar to dd(1)'s size syntax. |
| 408 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 409 | @item info [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] [-U] @var{filename} |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 410 | |
| 411 | Give information about the disk image @var{filename}. Use it in |
| 412 | particular to know the size reserved on disk which can be different |
bellard | 19d3679 | 2006-08-07 21:34:34 +0000 | [diff] [blame] | 413 | from the displayed size. If VM snapshots are stored in the disk image, |
Max Reitz | 987402c | 2019-05-15 09:59:16 +0200 | [diff] [blame] | 414 | they are displayed too. |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 415 | |
Kashyap Chamarthy | e535756 | 2012-10-18 11:25:34 +0530 | [diff] [blame] | 416 | If a disk image has a backing file chain, information about each disk image in |
| 417 | the chain can be recursively enumerated by using the option @code{--backing-chain}. |
| 418 | |
| 419 | For instance, if you have an image chain like: |
| 420 | |
| 421 | @example |
| 422 | base.qcow2 <- snap1.qcow2 <- snap2.qcow2 |
| 423 | @end example |
| 424 | |
| 425 | To enumerate information about each disk image in the above chain, starting from top to base, do: |
| 426 | |
| 427 | @example |
| 428 | qemu-img info --backing-chain snap2.qcow2 |
| 429 | @end example |
| 430 | |
Max Reitz | 987402c | 2019-05-15 09:59:16 +0200 | [diff] [blame] | 431 | The command can output in the format @var{ofmt} which is either @code{human} or |
| 432 | @code{json}. The JSON output is an object of QAPI type @code{ImageInfo}; with |
| 433 | @code{--backing-chain}, it is an array of @code{ImageInfo} objects. |
| 434 | |
Max Reitz | 4db4390 | 2019-05-15 09:59:17 +0200 | [diff] [blame] | 435 | @code{--output=human} reports the following information (for every image in the |
| 436 | chain): |
| 437 | @table @var |
| 438 | @item image |
| 439 | The image file name |
| 440 | |
| 441 | @item file format |
| 442 | The image format |
| 443 | |
| 444 | @item virtual size |
| 445 | The size of the guest disk |
| 446 | |
| 447 | @item disk size |
| 448 | How much space the image file occupies on the host file system (may be shown as |
| 449 | 0 if this information is unavailable, e.g. because there is no file system) |
| 450 | |
| 451 | @item cluster_size |
| 452 | Cluster size of the image format, if applicable |
| 453 | |
| 454 | @item encrypted |
| 455 | Whether the image is encrypted (only present if so) |
| 456 | |
| 457 | @item cleanly shut down |
| 458 | This is shown as @code{no} if the image is dirty and will have to be |
| 459 | auto-repaired the next time it is opened in qemu. |
| 460 | |
| 461 | @item backing file |
| 462 | The backing file name, if present |
| 463 | |
| 464 | @item backing file format |
| 465 | The format of the backing file, if the image enforces it |
| 466 | |
| 467 | @item Snapshot list |
| 468 | A list of all internal snapshots |
| 469 | |
| 470 | @item Format specific information |
| 471 | Further information whose structure depends on the image format. This section |
| 472 | is a textual representation of the respective @code{ImageInfoSpecific*} QAPI |
| 473 | object (e.g. @code{ImageInfoSpecificQCow2} for qcow2 images). |
| 474 | @end table |
| 475 | |
John Snow | 13c24ed | 2019-04-09 17:06:55 -0400 | [diff] [blame] | 476 | @item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [-U] @var{filename} |
Paolo Bonzini | facd6e2 | 2013-09-04 19:00:34 +0200 | [diff] [blame] | 477 | |
| 478 | Dump the metadata of image @var{filename} and its backing file chain. |
| 479 | In particular, this commands dumps the allocation state of every sector |
| 480 | of @var{filename}, together with the topmost file that allocates it in |
| 481 | the backing file chain. |
| 482 | |
| 483 | Two option formats are possible. The default format (@code{human}) |
| 484 | only dumps known-nonzero areas of the file. Known-zero parts of the |
| 485 | file are omitted altogether, and likewise for parts that are not allocated |
| 486 | throughout the chain. @command{qemu-img} output will identify a file |
| 487 | from where the data can be read, and the offset in the file. Each line |
| 488 | will include four fields, the first three of which are hexadecimal |
| 489 | numbers. For example the first line of: |
| 490 | @example |
| 491 | Offset Length Mapped to File |
| 492 | 0 0x20000 0x50000 /tmp/overlay.qcow2 |
| 493 | 0x100000 0x10000 0x95380000 /tmp/backing.qcow2 |
| 494 | @end example |
| 495 | @noindent |
| 496 | means that 0x20000 (131072) bytes starting at offset 0 in the image are |
| 497 | available in /tmp/overlay.qcow2 (opened in @code{raw} format) starting |
| 498 | at offset 0x50000 (327680). Data that is compressed, encrypted, or |
| 499 | otherwise not available in raw format will cause an error if @code{human} |
| 500 | format is in use. Note that file names can include newlines, thus it is |
| 501 | not safe to parse this output format in scripts. |
| 502 | |
| 503 | The alternative format @code{json} will return an array of dictionaries |
| 504 | in JSON format. It will include similar information in |
| 505 | the @code{start}, @code{length}, @code{offset} fields; |
| 506 | it will also include other more specific information: |
| 507 | @itemize @minus |
| 508 | @item |
| 509 | whether the sectors contain actual data or not (boolean field @code{data}; |
| 510 | if false, the sectors are either unallocated or stored as optimized |
| 511 | all-zero clusters); |
| 512 | |
| 513 | @item |
| 514 | whether the data is known to read as zero (boolean field @code{zero}); |
| 515 | |
| 516 | @item |
| 517 | in order to make the output shorter, the target file is expressed as |
| 518 | a @code{depth}; for example, a depth of 2 refers to the backing file |
| 519 | of the backing file of @var{filename}. |
| 520 | @end itemize |
| 521 | |
| 522 | In JSON format, the @code{offset} field is optional; it is absent in |
| 523 | cases where @code{human} format would omit the entry or exit with an error. |
| 524 | If @code{data} is false and the @code{offset} field is present, the |
| 525 | corresponding sectors in the file are not yet in use, but they are |
| 526 | preallocated. |
| 527 | |
| 528 | For more information, consult @file{include/block/block.h} in QEMU's |
| 529 | source code. |
| 530 | |
Stefan Hajnoczi | fd03c2b | 2017-07-05 13:57:36 +0100 | [diff] [blame] | 531 | @item measure [--output=@var{ofmt}] [-O @var{output_fmt}] [-o @var{options}] [--size @var{N} | [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-l @var{snapshot_param}] @var{filename}] |
| 532 | |
| 533 | Calculate the file size required for a new image. This information can be used |
| 534 | to size logical volumes or SAN LUNs appropriately for the image that will be |
| 535 | placed in them. The values reported are guaranteed to be large enough to fit |
| 536 | the image. The command can output in the format @var{ofmt} which is either |
Max Reitz | 987402c | 2019-05-15 09:59:16 +0200 | [diff] [blame] | 537 | @code{human} or @code{json}. The JSON output is an object of QAPI type |
| 538 | @code{BlockMeasureInfo}. |
Stefan Hajnoczi | fd03c2b | 2017-07-05 13:57:36 +0100 | [diff] [blame] | 539 | |
| 540 | If the size @var{N} is given then act as if creating a new empty image file |
| 541 | using @command{qemu-img create}. If @var{filename} is given then act as if |
| 542 | converting an existing image file using @command{qemu-img convert}. The format |
| 543 | of the new file is given by @var{output_fmt} while the format of an existing |
| 544 | file is given by @var{fmt}. |
| 545 | |
| 546 | A snapshot in an existing image can be specified using @var{snapshot_param}. |
| 547 | |
| 548 | The following fields are reported: |
| 549 | @example |
| 550 | required size: 524288 |
| 551 | fully allocated size: 1074069504 |
| 552 | @end example |
| 553 | |
| 554 | The @code{required size} is the file size of the new image. It may be smaller |
| 555 | than the virtual disk size if the image format supports compact representation. |
| 556 | |
| 557 | The @code{fully allocated size} is the file size of the new image once data has |
| 558 | been written to all sectors. This is the maximum size that the image file can |
| 559 | occupy with the exception of internal snapshots, dirty bitmaps, vmstate data, |
| 560 | and other advanced image format features. |
| 561 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 562 | @item snapshot [--object @var{objectdef}] [--image-opts] [-U] [-q] [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}] @var{filename} |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 563 | |
| 564 | List, apply, create or delete snapshots in image @var{filename}. |
Stefan Hajnoczi | ae6b0ed | 2010-04-24 09:12:12 +0100 | [diff] [blame] | 565 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 566 | @item rebase [--object @var{objectdef}] [--image-opts] [-U] [-q] [-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] | 567 | |
| 568 | Changes the backing file of an image. Only the formats @code{qcow2} and |
| 569 | @code{qed} support changing the backing file. |
| 570 | |
| 571 | The backing file is changed to @var{backing_file} and (if the image format of |
| 572 | @var{filename} supports this) the backing file format is changed to |
Alex Bligh | a616673 | 2012-10-16 13:46:18 +0100 | [diff] [blame] | 573 | @var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty |
| 574 | string), then the image is rebased onto no backing file (i.e. it will exist |
| 575 | independently of any backing file). |
Kevin Wolf | e618469 | 2011-01-17 15:35:28 +0100 | [diff] [blame] | 576 | |
Fam Zheng | a16efd5 | 2017-08-04 22:36:58 +0800 | [diff] [blame] | 577 | If a relative path name is given, the backing file is looked up relative to |
| 578 | the directory containing @var{filename}. |
| 579 | |
Max Reitz | 4005595 | 2014-07-22 22:58:42 +0200 | [diff] [blame] | 580 | @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] | 581 | @var{src_cache} specifies the cache mode for reading backing files. |
Max Reitz | 4005595 | 2014-07-22 22:58:42 +0200 | [diff] [blame] | 582 | |
Kevin Wolf | e618469 | 2011-01-17 15:35:28 +0100 | [diff] [blame] | 583 | There are two different modes in which @code{rebase} can operate: |
| 584 | @table @option |
| 585 | @item Safe mode |
| 586 | This is the default mode and performs a real rebase operation. The new backing |
| 587 | file may differ from the old one and qemu-img rebase will take care of keeping |
| 588 | the guest-visible content of @var{filename} unchanged. |
| 589 | |
| 590 | In order to achieve this, any clusters that differ between @var{backing_file} |
| 591 | and the old backing file of @var{filename} are merged into @var{filename} |
| 592 | before actually changing the backing file. |
| 593 | |
| 594 | Note that the safe mode is an expensive operation, comparable to converting |
| 595 | an image. It only works if the old backing file still exists. |
| 596 | |
| 597 | @item Unsafe mode |
| 598 | qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the |
| 599 | backing file name and format of @var{filename} is changed without any checks |
| 600 | on the file contents. The user must take care of specifying the correct new |
| 601 | backing file, or the guest-visible content of the image will be corrupted. |
| 602 | |
| 603 | This mode is useful for renaming or moving the backing file to somewhere else. |
| 604 | It can be used without an accessible old backing file, i.e. you can use it to |
| 605 | fix an image whose backing file has already been moved/renamed. |
| 606 | @end table |
| 607 | |
Richard W.M. Jones | 9fda6ab | 2012-05-21 14:58:05 +0100 | [diff] [blame] | 608 | You can use @code{rebase} to perform a ``diff'' operation on two |
| 609 | disk images. This can be useful when you have copied or cloned |
| 610 | a guest, and you want to get back to a thin image on top of a |
| 611 | template or base image. |
| 612 | |
| 613 | Say that @code{base.img} has been cloned as @code{modified.img} by |
| 614 | copying it, and that the @code{modified.img} guest has run so there |
| 615 | are now some changes compared to @code{base.img}. To construct a thin |
| 616 | image called @code{diff.qcow2} that contains just the differences, do: |
| 617 | |
| 618 | @example |
| 619 | qemu-img create -f qcow2 -b modified.img diff.qcow2 |
| 620 | qemu-img rebase -b base.img diff.qcow2 |
| 621 | @end example |
| 622 | |
| 623 | At this point, @code{modified.img} can be discarded, since |
| 624 | @code{base.img + diff.qcow2} contains the same information. |
| 625 | |
John Snow | 9775fcd | 2018-05-03 18:56:47 -0400 | [diff] [blame] | 626 | @item resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--preallocation=@var{prealloc}] [-q] [--shrink] @var{filename} [+ | -]@var{size} |
Stefan Hajnoczi | ae6b0ed | 2010-04-24 09:12:12 +0100 | [diff] [blame] | 627 | |
| 628 | Change the disk image as if it had been created with @var{size}. |
| 629 | |
| 630 | Before using this command to shrink a disk image, you MUST use file system and |
| 631 | partitioning tools inside the VM to reduce allocated file systems and partition |
| 632 | sizes accordingly. Failure to do so will result in data loss! |
| 633 | |
Pavel Butsykin | 4ffca89 | 2017-09-18 15:42:27 +0300 | [diff] [blame] | 634 | When shrinking images, the @code{--shrink} option must be given. This informs |
| 635 | qemu-img that the user acknowledges all loss of data beyond the truncated |
| 636 | image's end. |
| 637 | |
Stefan Hajnoczi | ae6b0ed | 2010-04-24 09:12:12 +0100 | [diff] [blame] | 638 | After using this command to grow a disk image, you must use file system and |
| 639 | partitioning tools inside the VM to actually begin using the new space on the |
| 640 | device. |
Max Reitz | 6f176b4 | 2013-09-03 10:09:50 +0200 | [diff] [blame] | 641 | |
Max Reitz | dc5f690 | 2017-06-13 22:20:55 +0200 | [diff] [blame] | 642 | When growing an image, the @code{--preallocation} option may be used to specify |
| 643 | how the additional image area should be allocated on the host. See the format |
| 644 | description in the @code{NOTES} section which values are allowed. Using this |
| 645 | option may result in slightly more data being allocated than necessary. |
| 646 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 647 | @end table |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 648 | @c man end |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 649 | |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 650 | @ignore |
| 651 | @c man begin NOTES |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 652 | Supported image file formats: |
| 653 | |
| 654 | @table @option |
| 655 | @item raw |
| 656 | |
| 657 | Raw disk image format (default). This format has the advantage of |
| 658 | being simple and easily exportable to all other emulators. If your |
| 659 | file system supports @emph{holes} (for example in ext2 or ext3 on |
| 660 | Linux or NTFS on Windows), then only the written sectors will reserve |
| 661 | space. Use @code{qemu-img info} to know the real size used by the |
| 662 | image or @code{ls -ls} on Unix/Linux. |
| 663 | |
Hu Tao | 0624742 | 2014-09-10 17:05:48 +0800 | [diff] [blame] | 664 | Supported options: |
| 665 | @table @code |
| 666 | @item preallocation |
| 667 | Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}). |
| 668 | @code{falloc} mode preallocates space for image by calling posix_fallocate(). |
Max Reitz | fa27c47 | 2019-07-11 15:29:35 +0200 | [diff] [blame] | 669 | @code{full} mode preallocates space for image by writing data to underlying |
| 670 | storage. This data may or may not be zero, depending on the storage location. |
Hu Tao | 0624742 | 2014-09-10 17:05:48 +0800 | [diff] [blame] | 671 | @end table |
| 672 | |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 673 | @item qcow2 |
| 674 | QEMU image format, the most versatile format. Use it to have smaller |
| 675 | images (useful if your filesystem does not supports holes, for example |
| 676 | on Windows), optional AES encryption, zlib based compression and |
| 677 | support of multiple VM snapshots. |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 678 | |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 679 | Supported options: |
| 680 | @table @code |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 681 | @item compat |
Stefan Hajnoczi | 7fa9e1f | 2014-01-06 12:39:01 +0800 | [diff] [blame] | 682 | Determines the qcow2 version to use. @code{compat=0.10} uses the |
| 683 | 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] | 684 | @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] | 685 | newer understand (this is the default). Amongst others, this includes zero |
| 686 | clusters, which allow efficient copy-on-read for sparse images. |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 687 | |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 688 | @item backing_file |
| 689 | File name of a base image (see @option{create} subcommand) |
| 690 | @item backing_fmt |
| 691 | Image format of the base image |
| 692 | @item encryption |
Daniel P. Berrange | 136cd19 | 2014-01-22 15:47:10 +0000 | [diff] [blame] | 693 | 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] | 694 | |
Daniel P. Berrange | 136cd19 | 2014-01-22 15:47:10 +0000 | [diff] [blame] | 695 | The use of encryption in qcow and qcow2 images is considered to be flawed by |
| 696 | modern cryptography standards, suffering from a number of design problems: |
| 697 | |
| 698 | @itemize @minus |
Daniel P. Berrange | 0b4ee90 | 2017-06-23 17:24:02 +0100 | [diff] [blame] | 699 | @item |
| 700 | The AES-CBC cipher is used with predictable initialization vectors based |
Daniel P. Berrange | 136cd19 | 2014-01-22 15:47:10 +0000 | [diff] [blame] | 701 | on the sector number. This makes it vulnerable to chosen plaintext attacks |
| 702 | which can reveal the existence of encrypted data. |
Daniel P. Berrange | 0b4ee90 | 2017-06-23 17:24:02 +0100 | [diff] [blame] | 703 | @item |
| 704 | The user passphrase is directly used as the encryption key. A poorly |
Daniel P. Berrange | 136cd19 | 2014-01-22 15:47:10 +0000 | [diff] [blame] | 705 | chosen or short passphrase will compromise the security of the encryption. |
Daniel P. Berrange | 0b4ee90 | 2017-06-23 17:24:02 +0100 | [diff] [blame] | 706 | @item |
| 707 | In the event of the passphrase being compromised there is no way to |
Daniel P. Berrange | 136cd19 | 2014-01-22 15:47:10 +0000 | [diff] [blame] | 708 | change the passphrase to protect data in any qcow images. The files must |
| 709 | be cloned, using a different encryption passphrase in the new file. The |
| 710 | original file must then be securely erased using a program like shred, |
| 711 | though even this is ineffective with many modern storage technologies. |
Daniel P. Berrange | 0b4ee90 | 2017-06-23 17:24:02 +0100 | [diff] [blame] | 712 | @item |
| 713 | Initialization vectors used to encrypt sectors are based on the |
| 714 | guest virtual sector number, instead of the host physical sector. When |
| 715 | a disk image has multiple internal snapshots this means that data in |
| 716 | multiple physical sectors is encrypted with the same initialization |
| 717 | vector. With the CBC mode, this opens the possibility of watermarking |
| 718 | attacks if the attack can collect multiple sectors encrypted with the |
| 719 | same IV and some predictable data. Having multiple qcow2 images with |
| 720 | the same passphrase also exposes this weakness since the passphrase |
| 721 | is directly used as the key. |
Daniel P. Berrange | 136cd19 | 2014-01-22 15:47:10 +0000 | [diff] [blame] | 722 | @end itemize |
| 723 | |
| 724 | Use of qcow / qcow2 encryption is thus strongly discouraged. Users are |
| 725 | recommended to use an alternative encryption technology such as the |
| 726 | Linux dm-crypt / LUKS system. |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 727 | |
| 728 | @item cluster_size |
| 729 | Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster |
| 730 | sizes can improve the image file size whereas larger cluster sizes generally |
| 731 | provide better performance. |
| 732 | |
| 733 | @item preallocation |
Hu Tao | 0e4271b | 2014-09-10 17:05:49 +0800 | [diff] [blame] | 734 | Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc}, |
| 735 | @code{full}). An image with preallocated metadata is initially larger but can |
| 736 | improve performance when the image needs to grow. @code{falloc} and @code{full} |
| 737 | preallocations are like the same options of @code{raw} format, but sets up |
| 738 | metadata also. |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 739 | |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 740 | @item lazy_refcounts |
| 741 | If this option is set to @code{on}, reference count updates are postponed with |
| 742 | the goal of avoiding metadata I/O and improving performance. This is |
| 743 | particularly interesting with @option{cache=writethrough} which doesn't batch |
| 744 | metadata updates. The tradeoff is that after a host crash, the reference count |
| 745 | tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img |
| 746 | check -r all} is required, which may take some time. |
| 747 | |
| 748 | This option can only be enabled if @code{compat=1.1} is specified. |
| 749 | |
Chunyan Liu | 4ab1559 | 2014-06-30 14:29:58 +0800 | [diff] [blame] | 750 | @item nocow |
Chunyan Liu | bc3a7f9 | 2014-07-02 12:27:29 +0800 | [diff] [blame] | 751 | 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] | 752 | valid on btrfs, no effect on other file systems. |
| 753 | |
| 754 | Btrfs has low performance when hosting a VM image file, even more when the guest |
| 755 | on the VM also using btrfs as file system. Turning off COW is a way to mitigate |
| 756 | this bad performance. Generally there are two ways to turn off COW on btrfs: |
| 757 | a) Disable it by mounting with nodatacow, then all newly created files will be |
| 758 | NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option |
| 759 | does. |
| 760 | |
| 761 | Note: this option is only valid to new or empty files. If there is an existing |
| 762 | file which is COW and has data blocks already, it couldn't be changed to NOCOW |
| 763 | 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] | 764 | the NOCOW flag is set or not (Capital 'C' is NOCOW flag). |
Chunyan Liu | 4ab1559 | 2014-06-30 14:29:58 +0800 | [diff] [blame] | 765 | |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 766 | @end table |
| 767 | |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 768 | @item Other |
| 769 | QEMU also supports various other image file formats for compatibility with |
Jeff Cody | 8282db1 | 2013-12-17 13:56:06 -0500 | [diff] [blame] | 770 | older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), VHDX, |
| 771 | 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] | 772 | For a more detailed description of these formats, see the QEMU Emulation User |
| 773 | Documentation. |
Stefan Hajnoczi | f085800 | 2012-06-13 14:29:15 +0100 | [diff] [blame] | 774 | |
Kevin Wolf | d3067b0 | 2012-11-21 14:21:47 +0100 | [diff] [blame] | 775 | The main purpose of the block drivers for these formats is image conversion. |
| 776 | For running VMs, it is recommended to convert the disk images to either raw or |
| 777 | qcow2 in order to achieve good performance. |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 778 | @end table |
| 779 | |
| 780 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 781 | @c man end |
| 782 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 783 | @setfilename qemu-img |
| 784 | @settitle QEMU disk image utility |
| 785 | |
| 786 | @c man begin SEEALSO |
| 787 | The HTML documentation of QEMU for more precise information and Linux |
| 788 | user mode emulator invocation. |
| 789 | @c man end |
| 790 | |
| 791 | @c man begin AUTHOR |
| 792 | Fabrice Bellard |
| 793 | @c man end |
| 794 | |
| 795 | @end ignore |