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