bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 1 | @example |
| 2 | @c man begin SYNOPSIS |
| 3 | usage: qemu-img command [command options] |
| 4 | @c man end |
| 5 | @end example |
| 6 | |
| 7 | @c man begin OPTIONS |
| 8 | |
| 9 | The following commands are supported: |
Stuart Brady | 153859b | 2009-06-07 00:42:17 +0100 | [diff] [blame] | 10 | |
| 11 | @include qemu-img-cmds.texi |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 12 | |
| 13 | Command parameters: |
| 14 | @table @var |
| 15 | @item filename |
| 16 | is a disk image filename |
ths | 5fafdf2 | 2007-09-16 21:08:06 +0000 | [diff] [blame] | 17 | @item fmt |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 18 | is the disk image format. It is guessed automatically in most cases. See below |
| 19 | for a description of the supported disk formats. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 20 | |
ths | 5fafdf2 | 2007-09-16 21:08:06 +0000 | [diff] [blame] | 21 | @item size |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 22 | is the disk image size in bytes. Optional suffixes @code{k} or @code{K} |
| 23 | (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M) |
| 24 | and T (terabyte, 1024G) are supported. @code{b} is ignored. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 25 | |
| 26 | @item output_filename |
ths | 5fafdf2 | 2007-09-16 21:08:06 +0000 | [diff] [blame] | 27 | is the destination disk image filename |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 28 | |
| 29 | @item output_fmt |
| 30 | is the destination format |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 31 | @item options |
| 32 | is a comma separated list of format specific options in a |
| 33 | 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] | 34 | by the used format or see the format descriptions below for details. |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 35 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 36 | |
| 37 | @item -c |
| 38 | indicates that target image must be compressed (qcow format only) |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 39 | @item -h |
| 40 | with or without a command shows help and lists the supported formats |
| 41 | @end table |
| 42 | |
| 43 | Parameters to snapshot subcommand: |
| 44 | |
| 45 | @table @option |
| 46 | |
| 47 | @item snapshot |
| 48 | is the name of the snapshot to create, apply or delete |
| 49 | @item -a |
| 50 | applies a snapshot (revert disk to saved state) |
| 51 | @item -c |
| 52 | creates a snapshot |
| 53 | @item -d |
| 54 | deletes a snapshot |
| 55 | @item -l |
| 56 | lists all snapshots in the given image |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 57 | @end table |
| 58 | |
| 59 | Command description: |
| 60 | |
| 61 | @table @option |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 62 | @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}] |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 63 | |
| 64 | Create the new disk image @var{filename} of size @var{size} and format |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 65 | @var{fmt}. Depending on the file format, you can add one or more @var{options} |
| 66 | that enable additional features of this format. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 67 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 68 | If the option @var{backing_file} is specified, then the image will record |
| 69 | only the differences from @var{backing_file}. No size needs to be specified in |
| 70 | this case. @var{backing_file} will never be modified unless you use the |
| 71 | @code{commit} monitor command (or qemu-img commit). |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 72 | |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 73 | The size can also be specified using the @var{size} option with @code{-o}, |
| 74 | it doesn't need to be specified separately in this case. |
| 75 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 76 | @item commit [-f @var{fmt}] @var{filename} |
| 77 | |
| 78 | Commit the changes recorded in @var{filename} in its base image. |
| 79 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 80 | @item convert [-c] [-f @var{fmt}] [-O @var{output_fmt}] [-o @var{options}] @var{filename} [@var{filename2} [...]] @var{output_filename} |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 81 | |
| 82 | Convert the disk image @var{filename} to disk image @var{output_filename} |
Kevin Wolf | eff4426 | 2009-06-04 15:39:39 +0200 | [diff] [blame] | 83 | using format @var{output_fmt}. It can be optionally compressed (@code{-c} |
| 84 | option) or use any format specific options like encryption (@code{-o} option). |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 85 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 86 | Only the formats @code{qcow} and @code{qcow2} support compression. The |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 87 | compression is read-only. It means that if a compressed sector is |
| 88 | rewritten, then it is rewritten as uncompressed data. |
| 89 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 90 | Image conversion is also useful to get smaller image when using a |
| 91 | growable format such as @code{qcow} or @code{cow}: the empty sectors |
| 92 | are detected and suppressed from the destination image. |
| 93 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 94 | You can use the @var{backing_file} option to force the output image to be |
| 95 | created as a copy on write image of the specified base image; the |
| 96 | @var{backing_file} should have the same content as the input's base image, |
| 97 | however the path, image format, etc may differ. |
| 98 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 99 | @item info [-f @var{fmt}] @var{filename} |
| 100 | |
| 101 | Give information about the disk image @var{filename}. Use it in |
| 102 | particular to know the size reserved on disk which can be different |
bellard | 19d3679 | 2006-08-07 21:34:34 +0000 | [diff] [blame] | 103 | from the displayed size. If VM snapshots are stored in the disk image, |
| 104 | they are displayed too. |
blueswir1 | d2c639d | 2009-01-24 18:19:25 +0000 | [diff] [blame] | 105 | |
| 106 | @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename} |
| 107 | |
| 108 | List, apply, create or delete snapshots in image @var{filename}. |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 109 | @end table |
| 110 | |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 111 | Supported image file formats: |
| 112 | |
| 113 | @table @option |
| 114 | @item raw |
| 115 | |
| 116 | Raw disk image format (default). This format has the advantage of |
| 117 | being simple and easily exportable to all other emulators. If your |
| 118 | file system supports @emph{holes} (for example in ext2 or ext3 on |
| 119 | Linux or NTFS on Windows), then only the written sectors will reserve |
| 120 | space. Use @code{qemu-img info} to know the real size used by the |
| 121 | image or @code{ls -ls} on Unix/Linux. |
| 122 | |
| 123 | @item host_device |
| 124 | |
| 125 | Host device format. This format should be used instead of raw when |
| 126 | converting to block devices or other devices where "holes" are not |
| 127 | supported. |
| 128 | |
| 129 | @item qcow2 |
| 130 | QEMU image format, the most versatile format. Use it to have smaller |
| 131 | images (useful if your filesystem does not supports holes, for example |
| 132 | on Windows), optional AES encryption, zlib based compression and |
| 133 | support of multiple VM snapshots. |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 134 | |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 135 | Supported options: |
| 136 | @table @code |
| 137 | @item backing_file |
| 138 | File name of a base image (see @option{create} subcommand) |
| 139 | @item backing_fmt |
| 140 | Image format of the base image |
| 141 | @item encryption |
| 142 | If this option is set to @code{on}, the image is encrypted. |
| 143 | |
Kevin Wolf | 8063d0f | 2009-10-28 12:49:16 +0100 | [diff] [blame] | 144 | Encryption uses the AES format which is very secure (128 bit keys). Use |
| 145 | a long password (16 characters) to get maximum protection. |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 146 | |
| 147 | @item cluster_size |
| 148 | Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster |
| 149 | sizes can improve the image file size whereas larger cluster sizes generally |
| 150 | provide better performance. |
| 151 | |
| 152 | @item preallocation |
| 153 | Preallocation mode (allowed values: off, metadata). An image with preallocated |
| 154 | metadata is initially larger but can improve performance when the image needs |
| 155 | to grow. |
| 156 | |
| 157 | @end table |
| 158 | |
| 159 | |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 160 | @item qcow |
| 161 | Old QEMU image format. Left for compatibility. |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 162 | |
| 163 | Supported options: |
| 164 | @table @code |
| 165 | @item backing_file |
| 166 | File name of a base image (see @option{create} subcommand) |
| 167 | @item encryption |
| 168 | If this option is set to @code{on}, the image is encrypted. |
| 169 | @end table |
| 170 | |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 171 | @item cow |
| 172 | User Mode Linux Copy On Write image format. Used to be the only growable |
| 173 | image format in QEMU. It is supported only for compatibility with |
| 174 | previous versions. It does not work on win32. |
| 175 | @item vdi |
| 176 | VirtualBox 1.1 compatible image format. |
| 177 | @item vmdk |
| 178 | VMware 3 and 4 compatible image format. |
Kevin Wolf | 3e03236 | 2009-10-28 12:49:17 +0100 | [diff] [blame] | 179 | |
| 180 | Supported options: |
| 181 | @table @code |
| 182 | @item backing_fmt |
| 183 | Image format of the base image |
| 184 | @item compat6 |
| 185 | Create a VMDK version 6 image (instead of version 4) |
| 186 | @end table |
| 187 | |
| 188 | @item vpc |
| 189 | VirtualPC compatible image format (VHD). |
| 190 | |
Kevin Wolf | f932c04 | 2009-10-28 12:49:15 +0100 | [diff] [blame] | 191 | @item cloop |
| 192 | Linux Compressed Loop image, useful only to reuse directly compressed |
| 193 | CD-ROM images present for example in the Knoppix CD-ROMs. |
| 194 | @end table |
| 195 | |
| 196 | |
bellard | acd935e | 2004-11-15 22:57:26 +0000 | [diff] [blame] | 197 | @c man end |
| 198 | |
| 199 | @ignore |
| 200 | |
| 201 | @setfilename qemu-img |
| 202 | @settitle QEMU disk image utility |
| 203 | |
| 204 | @c man begin SEEALSO |
| 205 | The HTML documentation of QEMU for more precise information and Linux |
| 206 | user mode emulator invocation. |
| 207 | @c man end |
| 208 | |
| 209 | @c man begin AUTHOR |
| 210 | Fabrice Bellard |
| 211 | @c man end |
| 212 | |
| 213 | @end ignore |