Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
QEMU-IMG(1)			     QEMU			   QEMU-IMG(1)

NAME
       qemu-img	- QEMU disk image utility

SYNOPSIS
       qemu-img	[standard options] command [command options]

DESCRIPTION
       qemu-img	 allows	 you  to create, convert and modify images offline. It
       can handle all image formats supported by QEMU.

       Warning:	Never use qemu-img to modify images in use by a	 running  vir-
       tual machine or any other process; this may destroy the image. Also, be
       aware that querying an image that is being modified by another  process
       may encounter inconsistent state.

OPTIONS
       Standard	options:

       -h, --help
	      Display this help	and exit

       -V, --version
	      Display version information and exit

       -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
	      Specify tracing options.

	      [enable=]PATTERN
		     Immediately  enable events	matching PATTERN (either event
		     name or a globbing	pattern).  This	option is only	avail-
		     able  if  QEMU  has been compiled with the	simple,	log or
		     ftrace tracing backend.  To specify  multiple  events  or
		     patterns, specify the -trace option multiple times.

		     Use -trace	help to	print a	list of	names of trace points.

	      events=FILE
		     Immediately  enable events	listed in FILE.	 The file must
		     contain one event name (as	listed in the trace-events-all
		     file) per line; globbing patterns are accepted too.  This
		     option is only available if QEMU has been	compiled  with
		     the simple, log or	ftrace tracing backend.

	      file=FILE
		     Log output	traces to FILE.	 This option is	only available
		     if	QEMU has been compiled with the	simple	tracing	 back-
		     end.

       The following commands are supported:

       amend [--object OBJECTDEF] [--image-opts] [-p] [-q] [-f FMT] [-t	CACHE]
       -o OPTIONS FILENAME

       bench [-c COUNT]	[-d DEPTH] [-f FMT]  [--flush-interval=FLUSH_INTERVAL]
       [-i  AIO]  [-n]	[--no-drain]  [-o OFFSET] [--pattern=PATTERN] [-q] [-s
       BUFFER_SIZE] [-S	STEP_SIZE] [-t CACHE] [-w] [-U]	FILENAME

       check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT]
       [-r [leaks | all]] [-T SRC_CACHE] [-U] FILENAME

       commit [--object	OBJECTDEF] [--image-opts] [-q] [-f FMT]	[-t CACHE] [-b
       BASE] [-d] [-p] FILENAME

       compare [--object OBJECTDEF]  [--image-opts]  [-f  FMT]	[-F  FMT]  [-T
       SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1	FILENAME2

       convert	 [--object   OBJECTDEF]	 [--image-opts]	 [--target-image-opts]
       [--target-is-zero] [-U] [-C] [-c] [-p] [-q] [-n]	[-f  FMT]  [-t	CACHE]
       [-T SRC_CACHE] [-O OUTPUT_FMT] [-B BACKING_FILE]	[-o OPTIONS] [-l SNAP-
       SHOT_PARAM] [-S SPARSE_SIZE] [-m	NUM_COROUTINES]	[-W] [--salvage] FILE-
       NAME [FILENAME2 [...]] OUTPUT_FILENAME

       create  [--object  OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE] [-F BACK-
       ING_FMT]	[-u] [-o OPTIONS] FILENAME [SIZE]

       dd  [--image-opts]  [-U]	 [-f  FMT]  [-O	 OUTPUT_FMT]   [bs=BLOCK_SIZE]
       [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT

       info  [--object	OBJECTDEF]  [--image-opts]  [-f	 FMT]  [--output=OFMT]
       [--backing-chain] [-U] FILENAME

       map [--object OBJECTDEF]	[--image-opts] [-f FMT]	 [--output=OFMT]  [-U]
       FILENAME

       measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N |	[--ob-
       ject OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]

       snapshot	[--object OBJECTDEF] [--image-opts] [-U] [-q] [-l |  -a	 SNAP-
       SHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME

       rebase  [--object  OBJECTDEF]  [--image-opts]  [-U]  [-q]  [-f FMT] [-t
       CACHE] [-T SRC_CACHE] [-p] [-u] -b BACKING_FILE [-F BACKING_FMT]	 FILE-
       NAME

       resize  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]	 [--prealloca-
       tion=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE

       Command parameters:

       FILENAME	is a disk image	filename.

       FMT is the disk image format.  It  is  guessed  automatically  in  most
       cases. See below	for a description of the supported disk	formats.

       SIZE  is	 the disk image	size in	bytes. Optional	suffixes k or K	(kilo-
       byte, 1024) M (megabyte,	1024k) and G (gigabyte,	 1024M)	 and  T	 (ter-
       abyte, 1024G) are supported.  b is ignored.

       OUTPUT_FILENAME is the destination disk image filename.

       OUTPUT_FMT is the destination format.

       OPTIONS	is  a  comma  separated	 list  of format specific options in a
       name=value format. Use -o ? for an overview of the options supported by
       the used	format or see the format descriptions below for	details.

       SNAPSHOT_PARAM  is  param  used for internal snapshot, format is	'snap-
       shot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'.

       --object	OBJECTDEF
	      is a QEMU	user creatable object definition. See the qemu(1) man-
	      ual  page	 for  a	description of the object properties. The most
	      common object type is a secret, which is used  to	 supply	 pass-
	      words and/or encryption keys.

       --image-opts
	      Indicates	 that  the  source  FILENAME parameter is to be	inter-
	      preted as	a full option string, not a plain filename.  This  pa-
	      rameter is mutually exclusive with the -f	parameter.

       --target-image-opts
	      Indicates	that the OUTPUT_FILENAME parameter(s) are to be	inter-
	      preted as	a full option string, not a plain filename.  This  pa-
	      rameter is mutually exclusive with the -O	parameters. It is cur-
	      rently required to also use the -n parameter to skip image  cre-
	      ation. This restriction may be relaxed in	a future release.

       --force-share (-U)
	      If  specified,  qemu-img will open the image in shared mode, al-
	      lowing other QEMU	processes to open it in	write mode. For	 exam-
	      ple,  this can be	used to	get the	image information (with	'info'
	      subcommand) when the image is used by  a	running	 guest.	  Note
	      that  this could produce inconsistent results because of concur-
	      rent metadata changes, etc. This option  is  only	 allowed  when
	      opening images in	read-only mode.

       --backing-chain
	      Will  enumerate  information about backing files in a disk image
	      chain. Refer below for further description.

       -c     Indicates	that target image  must	 be  compressed	 (qcow	format
	      only).

       -h     With  or	without	 a command, shows help and lists the supported
	      formats.

       -p     Display progress	bar  (compare,	convert	 and  rebase  commands
	      only).  If the -p	option is not used for a command that supports
	      it, the progress is reported when	the process receives a SIGUSR1
	      or SIGINFO signal.

       -q     Quiet mode - do not print	any output (except errors). There's no
	      progress bar in case both	-q and -p options are used.

       -S SIZE
	      Indicates	the consecutive	number of bytes	that must contain only
	      zeros  for  qemu-img to create a sparse image during conversion.
	      This value is rounded down to the	nearest	512 bytes. You may use
	      the common size suffixes like k for kilobytes.

       -t CACHE
	      Specifies	 the cache mode	that should be used with the (destina-
	      tion) file. See  the  documentation  of  the  emulator's	-drive
	      cache=...	option for allowed values.

       -T SRC_CACHE
	      Specifies	 the  cache  mode  that	should be used with the	source
	      file(s).	See  the  documentation	 of  the   emulator's	-drive
	      cache=...	option for allowed values.

       Parameters to snapshot subcommand:

       snapshot
	      Is the name of the snapshot to create, apply or delete

       -a     Applies a	snapshot (revert disk to saved state)

       -c     Creates a	snapshot

       -d     Deletes a	snapshot

       -l     Lists all	snapshots in the given image

       Parameters to compare subcommand:

       -f     First image format

       -F     Second image format

       -s     Strict mode - fail on different image size or sector allocation

       Parameters to convert subcommand:

       -n     Skip the creation	of the target volume

       -m     Number of	parallel coroutines for	the convert process

       -W     Allow  out-of-order  writes  to the destination. This option im-
	      proves performance, but is only recommended for preallocated de-
	      vices like host devices or other raw block devices.

       -C     Try  to  use  copy  offloading to	move data from source image to
	      target. This may improve performance if the data is remote, such
	      as  with NFS or iSCSI backends, but will not automatically spar-
	      sify zero	sectors, and may result	in a  fully  allocated	target
	      image  depending	on the host support for	getting	allocation in-
	      formation.

       --salvage
	      Try to ignore I/O	errors when reading.   Unless  in  quiet  mode
	      (-q),  errors  will still	be printed.  Areas that	cannot be read
	      from the source will be treated as containing only zeroes.

       --target-is-zero
	      Assume that reading the destination image	will always return ze-
	      ros. This	parameter is mutually exclusive	with a destination im-
	      age that has a backing file. It is required to also use  the  -n
	      parameter	to skip	image creation.

       Parameters to dd	subcommand:

       bs=BLOCK_SIZE
	      Defines the block	size

       count=BLOCKS
	      Sets the number of input blocks to copy

       if=INPUT
	      Sets the input file

       of=OUTPUT
	      Sets the output file

       skip=BLOCKS
	      Sets the number of input blocks to skip

       Command description:

       amend [--object OBJECTDEF] [--image-opts] [-p] [-q] [-f FMT] [-t	CACHE]
       -o OPTIONS FILENAME
	      Amends the image format specific	OPTIONS	 for  the  image  file
	      FILENAME.	Not all	file formats support this operation.

       bench  [-c COUNT] [-d DEPTH] [-f	FMT] [--flush-interval=FLUSH_INTERVAL]
       [-i AIO]	[-n] [--no-drain] [-o  OFFSET]	[--pattern=PATTERN]  [-q]  [-s
       BUFFER_SIZE] [-S	STEP_SIZE] [-t CACHE] [-w] [-U]	FILENAME
	      Run a simple sequential I/O benchmark on the specified image. If
	      -w is specified, a write test is	performed,  otherwise  a  read
	      test is performed.

	      A	 total	number	of  COUNT I/O requests is performed, each BUF-
	      FER_SIZE bytes in	size, and with DEPTH requests in parallel. The
	      first  request starts at the position given by OFFSET, each fol-
	      lowing request increases the current position by	STEP_SIZE.  If
	      STEP_SIZE	is not given, BUFFER_SIZE is used for its value.

	      If  FLUSH_INTERVAL  is  specified	 for a write test, the request
	      queue is drained and a flush is issued  before  new  writes  are
	      made  whenever the number	of remaining requests is a multiple of
	      FLUSH_INTERVAL. If additionally --no-drain is specified, a flush
	      is issued	without	draining the request queue first.

	      if  -i is	specified, AIO option can be used to specify different
	      AIO backends: threads, native or io_uring.

	      If -n is specified, the native AIO backend is used if  possible.
	      On  Linux, this option only works	if -t none or -t directsync is
	      specified	as well.

	      For write	tests, by default a buffer filled with zeros is	 writ-
	      ten.  This  can  be  overridden with a pattern byte specified by
	      PATTERN.

       check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT]
       [-r [leaks | all]] [-T SRC_CACHE] [-U] FILENAME
	      Perform a	consistency check on the disk image FILENAME. The com-
	      mand can output in the format OFMT  which	 is  either  human  or
	      json.  The JSON output is	an object of QAPI type ImageCheck.

	      If -r is specified, qemu-img tries to repair any inconsistencies
	      found during the check. -r leaks	repairs	 only  cluster	leaks,
	      whereas  -r all fixes all	kinds of errors, with a	higher risk of
	      choosing the wrong fix or	hiding corruption that has already oc-
	      curred.

	      Only the formats qcow2, qed and vdi support consistency checks.

	      In case the image	does not have any inconsistencies, check exits
	      with 0.  Other exit codes	indicate  the  kind  of	 inconsistency
	      found  or	 if another error occurred. The	following table	summa-
	      rizes all	exit codes of the check	subcommand:

	      0	     Check completed, the image	is (now) consistent

	      1	     Check not completed because of internal errors

	      2	     Check completed, image is corrupted

	      3	     Check completed, image has	leaked clusters,  but  is  not
		     corrupted

	      63     Checks are	not supported by the image format

	      If  -r is	specified, exit	codes representing the image state re-
	      fer to the state after (the attempt at) repairing	it. That is, a
	      successful  -r  all will yield the exit code 0, independently of
	      the image	state before.

       commit [--object	OBJECTDEF] [--image-opts] [-q] [-f FMT]	[-t CACHE] [-b
       BASE] [-d] [-p] FILENAME
	      Commit  the  changes  recorded  in FILENAME in its base image or
	      backing file.  If	the backing file is smaller than the snapshot,
	      then the backing file will be resized to be the same size	as the
	      snapshot.	 If the	snapshot is smaller than the backing file, the
	      backing  file  will  not	be truncated.  If you want the backing
	      file to match the	size of	the smaller snapshot, you  can	safely
	      truncate it yourself once	the commit operation successfully com-
	      pletes.

	      The image	FILENAME is emptied after the operation	has succeeded.
	      If  you  do  not need FILENAME afterwards	and intend to drop it,
	      you may skip emptying FILENAME by	specifying the -d flag.

	      If the backing chain of the given	image file FILENAME  has  more
	      than  one	layer, the backing file	into which the changes will be
	      committed	may be specified as BASE (which	 has  to  be  part  of
	      FILENAME's backing chain). If BASE is not	specified, the immedi-
	      ate backing file of the top image	(which is  FILENAME)  will  be
	      used. Note that after a commit operation all images between BASE
	      and the top image	will be	invalid	and may	 return	 garbage  data
	      when read. For this reason, -b implies -d	(so that the top image
	      stays valid).

       compare [--object OBJECTDEF]  [--image-opts]  [-f  FMT]	[-F  FMT]  [-T
       SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1	FILENAME2
	      Check  if	 two images have the same content. You can compare im-
	      ages with	different format or settings.

	      The format is probed unless you specify it by -f (used for FILE-
	      NAME1) and/or -F (used for FILENAME2) option.

	      By  default, images with different size are considered identical
	      if the larger image contains only	unallocated and/or zeroed sec-
	      tors  in the area	after the end of the other image. In addition,
	      if any sector is not allocated in	one image  and	contains  only
	      zero  bytes in the second	one, it	is evaluated as	equal. You can
	      use Strict mode by specifying the	-s option. When	 compare  runs
	      in  Strict mode, it fails	in case	image size differs or a	sector
	      is allocated in one image	and is not  allocated  in  the	second
	      one.

	      By  default,  compare  prints out	a result message. This message
	      displays information that	both images are	same or	 the  position
	      of the first different byte. In addition,	result message can re-
	      port different image size	in case	Strict mode is used.

	      Compare exits with 0 in case the images are equal	and with 1  in
	      case  the	images differ. Other exit codes	mean an	error occurred
	      during execution and standard error output should	contain	an er-
	      ror  message.   The  following table sumarizes all exit codes of
	      the compare subcommand:

	      0	     Images are	identical

	      1	     Images differ

	      2	     Error on opening an image

	      3	     Error on checking a sector	allocation

	      4	     Error on reading data

       convert	[--object  OBJECTDEF]	[--image-opts]	 [--target-image-opts]
       [--target-is-zero]  [-U]	 [-C]  [-c] [-p] [-q] [-n] [-f FMT] [-t	CACHE]
       [-T SRC_CACHE] [-O OUTPUT_FMT] [-B BACKING_FILE]	[-o OPTIONS] [-l SNAP-
       SHOT_PARAM]  [-S	 SPARSE_SIZE] [-m NUM_COROUTINES] [-W] FILENAME	[FILE-
       NAME2 [...]] OUTPUT_FILENAME
	      Convert the disk image FILENAME or a snapshot SNAPSHOT_PARAM  to
	      disk  image  OUTPUT_FILENAME  using format OUTPUT_FMT. It	can be
	      optionally compressed (-c	option)	or use any format specific op-
	      tions like encryption (-o	option).

	      Only  the	 formats  qcow and qcow2 support compression. The com-
	      pression is read-only. It	means that if a	compressed  sector  is
	      rewritten, then it is rewritten as uncompressed data.

	      Image  conversion	is also	useful to get smaller image when using
	      a	growable format	such as	qcow: the empty	sectors	 are  detected
	      and suppressed from the destination image.

	      SPARSE_SIZE  indicates the consecutive number of bytes (defaults
	      to 4k) that must contain only zeros for  qemu-img	 to  create  a
	      sparse  image during conversion. If SPARSE_SIZE is 0, the	source
	      will not be scanned for unallocated or  zero  sectors,  and  the
	      destination image	will always be fully allocated.

	      You can use the BACKING_FILE option to force the output image to
	      be created as a copy on write image of the specified base	image;
	      the  BACKING_FILE	 should	 have  the same	content	as the input's
	      base image, however the path, image format, etc may differ.

	      If a relative path name is given,	the backing file is looked  up
	      relative to the directory	containing OUTPUT_FILENAME.

	      If  the  -n option is specified, the target volume creation will
	      be skipped. This is useful for formats such as rbd if the	target
	      volume  has already been created with site specific options that
	      cannot be	supplied through qemu-img.

	      Out of order writes can be enabled with -W  to  improve  perfor-
	      mance.   This  is	only recommended for preallocated devices like
	      host devices or other raw	block devices. Out of order write does
	      not work in combination with creating compressed images.

	      NUM_COROUTINES  specifies	 how  many coroutines work in parallel
	      during the convert process (defaults to 8).

       create [--object	OBJECTDEF] [-q]	[-f FMT] [-b BACKING_FILE]  [-F	 BACK-
       ING_FMT]	[-u] [-o OPTIONS] FILENAME [SIZE]
	      Create  the new disk image FILENAME of size SIZE and format FMT.
	      Depending	on the file format, you	can add	one  or	 more  OPTIONS
	      that enable additional features of this format.

	      If  the  option  BACKING_FILE  is	specified, then	the image will
	      record only the differences from BACKING_FILE. No	size needs  to
	      be  specified  in	this case. BACKING_FILE	will never be modified
	      unless you use the commit	monitor	command	(or qemu-img commit).

	      If a relative path name is given,	the backing file is looked  up
	      relative to the directory	containing FILENAME.

	      Note  that  a given backing file will be opened to check that it
	      is valid.	Use the	-u option to enable unsafe backing file	 mode,
	      which  means  that the image will	be created even	if the associ-
	      ated backing file	cannot be opened. A matching backing file must
	      be  created  or  additional  options be used to make the backing
	      file specification valid when you	want to	use an	image  created
	      this way.

	      The size can also	be specified using the SIZE option with	-o, it
	      doesn't need to be specified separately in this case.

       dd  [--image-opts]  [-U]	 [-f  FMT]  [-O	 OUTPUT_FMT]   [bs=BLOCK_SIZE]
       [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT
	      dd  copies from INPUT file to OUTPUT file	converting it from FMT
	      format to	OUTPUT_FMT format.

	      The data is by default read and  written	using  blocks  of  512
	      bytes   but   can	 be  modified  by  specifying  BLOCK_SIZE.  If
	      count=BLOCKS is specified	dd will	stop reading input after read-
	      ing BLOCKS input blocks.

	      The size syntax is similar to dd(1)'s size syntax.

       info  [--object	OBJECTDEF]  [--image-opts]  [-f	 FMT]  [--output=OFMT]
       [--backing-chain] [-U] FILENAME
	      Give information about the disk image FILENAME. Use it  in  par-
	      ticular to know the size reserved	on disk	which can be different
	      from the displayed size. If VM snapshots are stored in the  disk
	      image, they are displayed	too.

	      If a disk	image has a backing file chain,	information about each
	      disk image in the	chain can be recursively enumerated  by	 using
	      the option --backing-chain.

	      For instance, if you have	an image chain like:

		 base.qcow2 <- snap1.qcow2 <- snap2.qcow2

	      To  enumerate  information  about	 each  disk image in the above
	      chain, starting from top to base,	do:

		 qemu-img info --backing-chain snap2.qcow2

	      The command can output in	the format OFMT	which is either	 human
	      or  json.	  The JSON output is an	object of QAPI type ImageInfo;
	      with --backing-chain, it is an array of ImageInfo	objects.

	      --output=human reports the following information (for every  im-
	      age in the chain):

	      image  The image file name

	      file format
		     The image format

	      virtual size
		     The size of the guest disk

	      disk size
		     How  much	space the image	file occupies on the host file
		     system (may be shown as 0 if this information is unavail-
		     able, e.g.	because	there is no file system)

	      cluster_size
		     Cluster size of the image format, if applicable

	      encrypted
		     Whether the image is encrypted (only present if so)

	      cleanly shut down
		     This  is  shown as	no if the image	is dirty and will have
		     to	be auto-repaired the next time it is opened in qemu.

	      backing file
		     The backing file name, if present

	      backing file format
		     The format	of the backing file, if	the image enforces it

	      Snapshot list
		     A list of all internal snapshots

	      Format specific information
		     Further information whose structure depends on the	 image
		     format.   This section is a textual representation	of the
		     respective	ImageInfoSpecific* QAPI	object (e.g.  ImageIn-
		     foSpecificQCow2 for qcow2 images).

       map  [--object  OBJECTDEF] [--image-opts] [-f FMT] [--output=OFMT] [-U]
       FILENAME
	      Dump the metadata	of image FILENAME and its backing file	chain.
	      In particular, this commands dumps the allocation	state of every
	      sector of	FILENAME, together with	the topmost  file  that	 allo-
	      cates it in the backing file chain.

	      Two  option  formats  are	 possible.  The	default	format (human)
	      only dumps known-nonzero areas of	the file.  Known-zero parts of
	      the file are omitted altogether, and likewise for	parts that are
	      not allocated throughout the chain.  qemu-img output will	 iden-
	      tify  a  file from where the data	can be read, and the offset in
	      the file.	 Each line will	include	four fields, the  first	 three
	      of  which	 are  hexadecimal numbers.  For	example	the first line
	      of:

		 Offset		 Length		 Mapped	to	 File
		 0		 0x20000	 0x50000	 /tmp/overlay.qcow2
		 0x100000	 0x10000	 0x95380000	 /tmp/backing.qcow2

	      means that 0x20000 (131072) bytes	starting at offset  0  in  the
	      image are	available in /tmp/overlay.qcow2	(opened	in raw format)
	      starting at offset 0x50000 (327680).  Data that  is  compressed,
	      encrypted,  or  otherwise	not available in raw format will cause
	      an error if human	format is in use.  Note	that  file  names  can
	      include  newlines, thus it is not	safe to	parse this output for-
	      mat in scripts.

	      The alternative format json will return an array of dictionaries
	      in  JSON	format.	  It  will  include similar information	in the
	      start, length, offset fields; it will also  include  other  more
	      specific information:

	      o	whether	 the sectors contain actual data or not	(boolean field
		data; if false,	the sectors are	either unallocated  or	stored
		as optimized all-zero clusters);

	      o	whether	 the  data  is	known  to  read	as zero	(boolean field
		zero);

	      o	in order to make the output shorter, the target	 file  is  ex-
		pressed	 as  a	depth; for example, a depth of 2 refers	to the
		backing	file of	the backing file of FILENAME.

	      In JSON format, the offset field is optional; it	is  absent  in
	      cases  where  human  format would	omit the entry or exit with an
	      error.  If data is false and the offset field  is	 present,  the
	      corresponding  sectors  in the file are not yet in use, but they
	      are preallocated.

	      For more information, consult  include/block/block.h  in	QEMU's
	      source code.

       measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N |	[--ob-
       ject OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]
	      Calculate	the file size required for a new image.	 This informa-
	      tion  can	 be used to size logical volumes or SAN	LUNs appropri-
	      ately for	the image that will be placed in them.	The values re-
	      ported  are guaranteed to	be large enough	to fit the image.  The
	      command can output in the	format OFMT which is either  human  or
	      json.   The  JSON	output is an object of QAPI type BlockMeasure-
	      Info.

	      If the size N is given then act as if creating a new empty image
	      file using qemu-img create.  If FILENAME is given	then act as if
	      converting an existing image file	using qemu-img	convert.   The
	      format  of  the new file is given	by OUTPUT_FMT while the	format
	      of an existing file is given by FMT.

	      A	snapshot in an existing	image can  be  specified  using	 SNAP-
	      SHOT_PARAM.

	      The following fields are reported:

		 required size:	524288
		 fully allocated size: 1074069504

	      The  required size is the	file size of the new image.  It	may be
	      smaller than the virtual disk size if the	image format  supports
	      compact representation.

	      The  fully allocated size	is the file size of the	new image once
	      data has been written to all sectors.  This is the maximum  size
	      that  the	 image	file can occupy	with the exception of internal
	      snapshots, dirty bitmaps,	vmstate	data, and other	advanced image
	      format features.

       snapshot	 [--object  OBJECTDEF] [--image-opts] [-U] [-q]	[-l | -a SNAP-
       SHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME
	      List, apply, create or delete snapshots in image FILENAME.

       rebase [--object	OBJECTDEF]  [--image-opts]  [-U]  [-q]	[-f  FMT]  [-t
       CACHE]  [-T SRC_CACHE] [-p] [-u]	-b BACKING_FILE	[-F BACKING_FMT] FILE-
       NAME
	      Changes the backing file of an image. Only the formats qcow2 and
	      qed support changing the backing file.

	      The  backing  file  is changed to	BACKING_FILE and (if the image
	      format of	FILENAME supports this)	the  backing  file  format  is
	      changed  to BACKING_FMT. If BACKING_FILE is specified as "" (the
	      empty string), then the image is rebased onto  no	 backing  file
	      (i.e. it will exist independently	of any backing file).

	      If  a relative path name is given, the backing file is looked up
	      relative to the directory	containing FILENAME.

	      CACHE specifies the cache	mode to	be used	for FILENAME,  whereas
	      SRC_CACHE	specifies the cache mode for reading backing files.

	      There are	two different modes in which rebase can	operate:

	      Safe mode
		     This is the default mode and performs a real rebase oper-
		     ation. The	new backing file may differ from the  old  one
		     and  qemu-img  rebase  will  take	care  of  keeping  the
		     guest-visible content of FILENAME unchanged.

		     In	order to achieve this, any clusters  that  differ  be-
		     tween  BACKING_FILE  and the old backing file of FILENAME
		     are merged	into FILENAME  before  actually	 changing  the
		     backing file.

		     Note that the safe	mode is	an expensive operation,	compa-
		     rable to converting an image. It only works  if  the  old
		     backing file still	exists.

	      Unsafe mode
		     qemu-img uses the unsafe mode if -u is specified. In this
		     mode, only	the backing file name and format  of  FILENAME
		     is	 changed  without any checks on	the file contents. The
		     user must take care of specifying the correct new backing
		     file,  or	the guest-visible content of the image will be
		     corrupted.

		     This mode is useful for renaming or  moving  the  backing
		     file to somewhere else.  It can be	used without an	acces-
		     sible old backing file, i.e. you can use it to fix	an im-
		     age whose backing file has	already	been moved/renamed.

	      You can use rebase to perform a "diff" operation on two disk im-
	      ages.  This can be useful	when  you  have	 copied	 or  cloned  a
	      guest, and you want to get back to a thin	image on top of	a tem-
	      plate or base image.

	      Say that base.img	has been cloned	as modified.img	by copying it,
	      and  that	 the  modified.img guest has run so there are now some
	      changes compared to base.img.  To	construct a thin image	called
	      diff.qcow2 that contains just the	differences, do:

		 qemu-img create -f qcow2 -b modified.img diff.qcow2
		 qemu-img rebase -b base.img diff.qcow2

	      At  this	point, modified.img can	be discarded, since base.img +
	      diff.qcow2 contains the same information.

       resize  [--object  OBJECTDEF]  [--image-opts]  [-f  FMT]	 [--prealloca-
       tion=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE
	      Change the disk image as if it had been created with SIZE.

	      Before  using  this command to shrink a disk image, you MUST use
	      file system and partitioning tools inside	the VM to reduce allo-
	      cated  file systems and partition	sizes accordingly.  Failure to
	      do so will result	in data	loss!

	      When shrinking images, the --shrink option must be  given.  This
	      informs qemu-img that the	user acknowledges all loss of data be-
	      yond the truncated image's end.

	      After using this command to grow a disk image, you must use file
	      system  and  partitioning	 tools inside the VM to	actually begin
	      using the	new space on the device.

	      When growing an image, the --preallocation option	may be used to
	      specify how the additional image area should be allocated	on the
	      host.  See the format description	in  the	 Notes	section	 which
	      values  are  allowed.   Using this option	may result in slightly
	      more data	being allocated	than necessary.

NOTES
       Supported image file formats:

       raw
	  Raw disk image format	(default). This	format has  the	 advantage  of
	  being	 simple	 and easily exportable to all other emulators. If your
	  file system supports holes (for example in ext2 or ext3 on Linux  or
	  NTFS	on Windows), then only the written sectors will	reserve	space.
	  Use qemu-img info to know the	real size used by the image or ls  -ls
	  on Unix/Linux.

	  Supported options:

	  preallocation
		 Preallocation mode (allowed values: off, falloc, full).  fal-
		 loc mode preallocates space for image by calling posix_fallo-
		 cate().   full	 mode  preallocates space for image by writing
		 data to underlying storage.  This data	 may  or  may  not  be
		 zero, depending on the	storage	location.

       qcow2
	  QEMU image format, the most versatile	format.	Use it to have smaller
	  images (useful if your filesystem does not supports holes, for exam-
	  ple on Windows), optional AES	encryption, zlib based compression and
	  support of multiple VM snapshots.

	  Supported options:

	  compat Determines the	qcow2 version to  use.	compat=0.10  uses  the
		 traditional  image  format that can be	read by	any QEMU since
		 0.10.	compat=1.1 enables image format	extensions  that  only
		 QEMU  1.1 and newer understand	(this is the default). Amongst
		 others, this includes zero clusters,  which  allow  efficient
		 copy-on-read for sparse images.

	  backing_file
		 File name of a	base image (see	create subcommand)

	  backing_fmt
		 Image format of the base image

	  encryption
		 If  this  option  is  set  to on, the image is	encrypted with
		 128-bit AES-CBC.

		 The use of encryption in qcow and qcow2 images	is  considered
		 to be flawed by modern	cryptography standards,	suffering from
		 a number of design problems:

		 o The AES-CBC cipher is used with predictable	initialization
		   vectors  based on the sector	number.	This makes it vulnera-
		   ble to chosen plaintext attacks which can reveal the	 exis-
		   tence of encrypted data.

		 o The user passphrase is directly used	as the encryption key.
		   A poorly chosen or short passphrase will compromise the se-
		   curity of the encryption.

		 o In  the  event of the passphrase being compromised there is
		   no way to change the	passphrase to protect data in any qcow
		   images. The files must be cloned, using a different encryp-
		   tion	passphrase in the new file.  The  original  file  must
		   then	 be securely erased using a program like shred,	though
		   even	this is	ineffective with many modern storage technolo-
		   gies.

		 o Initialization vectors used to encrypt sectors are based on
		   the guest virtual sector number, instead of the host	physi-
		   cal	sector.	 When a	disk image has multiple	internal snap-
		   shots this means that data in multiple physical sectors  is
		   encrypted with the same initialization vector. With the CBC
		   mode, this opens the	possibility of watermarking attacks if
		   the	attack can collect multiple sectors encrypted with the
		   same	IV and some predictable	data.  Having  multiple	 qcow2
		   images  with	the same passphrase also exposes this weakness
		   since the passphrase	is directly used as the	key.

		 Use of	qcow / qcow2 encryption	is thus	strongly  discouraged.
		 Users	are recommended	to use an alternative encryption tech-
		 nology	such as	the Linux dm-crypt / LUKS system.

	  cluster_size
		 Changes the qcow2 cluster size	(must be between 512 and  2M).
		 Smaller cluster sizes can improve the image file size whereas
		 larger	cluster	sizes generally	provide	better performance.

	  preallocation
		 Preallocation mode (allowed values:  off,  metadata,  falloc,
		 full).	 An  image  with  preallocated	metadata  is initially
		 larger	but can	improve	performance when the  image  needs  to
		 grow.	falloc	and  full preallocations are like the same op-
		 tions of raw format, but sets up metadata also.

	  lazy_refcounts
		 If this option	is set to  on,	reference  count  updates  are
		 postponed  with the goal of avoiding metadata I/O and improv-
		 ing  performance.  This  is  particularly  interesting	  with
		 cache=writethrough  which doesn't batch metadata updates. The
		 tradeoff is that after	a host crash, the reference count  ta-
		 bles  must  be	 rebuilt, i.e. on the next open	an (automatic)
		 qemu-img check	-r all is required, which may take some	time.

		 This option can only be enabled if compat=1.1 is specified.

	  nocow	 If this option	is set to on, it will  turn  off  COW  of  the
		 file.	It's only valid	on btrfs, no effect on other file sys-
		 tems.

		 Btrfs has low performance when	hosting	a VM image file,  even
		 more  when  the guest on the VM also using btrfs as file sys-
		 tem. Turning off COW is a way to mitigate  this  bad  perfor-
		 mance.	Generally there	are two	ways to	turn off COW on	btrfs:

		 o Disable  it by mounting with	nodatacow, then	all newly cre-
		   ated	files will be NOCOW

		 o For an empty	file, add the  NOCOW  file  attribute.	That's
		   what	this option does.

		 Note:	this  option  is  only valid to	new or empty files. If
		 there is an existing file which is COW	and  has  data	blocks
		 already, it couldn't be changed to NOCOW by setting nocow=on.
		 One can issue lsattr filename to check	if the NOCOW  flag  is
		 set or	not (Capital 'C' is NOCOW flag).

       Other
	  QEMU	also supports various other image file formats for compatibil-
	  ity with older QEMU versions or other	hypervisors,  including	 VMDK,
	  VDI,	VHD  (vpc),  VHDX, qcow1 and QED. For a	full list of supported
	  formats see qemu-img --help.	For a  more  detailed  description  of
	  these	formats, see the QEMU block drivers reference documentation.

	  The  main  purpose  of  the block drivers for	these formats is image
	  conversion.  For running VMs,	it is recommended to convert the  disk
	  images to either raw or qcow2	in order to achieve good performance.

AUTHOR
       Fabrice Bellard

COPYRIGHT
       2020, The QEMU Project Developers

5.0.0				 Aug 31, 2020			   QEMU-IMG(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=qemu-img&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help