with or without a command shows help and lists the supported formats
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.
Quiet mode - do not print any output (except errors). There’s no progress bar in case both -q and -p options are used.
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.
specifies the cache mode that should be used with the (destination) file. See
the documentation of the emulator’s -drive cache=...
option for allowed
values.
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:
is the name of the snapshot to create, apply or delete
applies a snapshot (revert disk to saved state)
creates a snapshot
deletes a snapshot
lists all snapshots in the given image
Parameters to compare subcommand:
First image format
Second image format
Strict mode - fail on different image size or sector allocation
Parameters to convert subcommand:
Skip the creation of the target volume
Number of parallel coroutines for the convert process
Allow out-of-order writes to the destination. This option improves performance, but is only recommended for preallocated devices like host devices or other raw block devices.
Parameters to dd subcommand:
defines the block size
sets the number of input blocks to copy
sets the input file
sets the output file
sets the number of input blocks to skip
Command description:
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 buffer_size bytes in size, and with depth requests in parallel. The first request starts at the position given by offset, each following 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 -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 written. This can be overridden with a pattern byte specified by pattern.
Perform a consistency check on the disk image filename. The command can
output in the format ofmt which is either human
or json
.
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 occurred.
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 summarizes all exit codes of the check subcommand:
Check completed, the image is (now) consistent
Check not completed because of internal errors
Check completed, image is corrupted
Check completed, image has leaked clusters, but is not corrupted
Checks are not supported by the image format
If -r
is specified, exit codes representing the image state refer 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.
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).
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 associated 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.
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 completes.
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 immediate backing file of the top
image (which is filename) will be used. For reasons of consistency,
explicitly specifying base will always imply -d
(since emptying an
image after committing to an indirect backing file would lead to different data
being read from the image due to content in the intermediate backing chain
overruling the commit target).
Check if two images have the same content. You can compare images with different format or settings.
The format is probed unless you specify it by -f (used for filename1) 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 sectors 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 report 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 error message.
The following table sumarizes all exit codes of the compare subcommand:
Images are identical
Images differ
Error on opening an image
Error on checking a sector allocation
Error on reading data
Convert the disk image filename or a snapshot snapshot_param(snapshot_id_or_name is deprecated)
to disk image output_filename using format output_fmt. It can be optionally compressed (-c
option) or use any format specific options like encryption (-o
option).
Only the formats qcow
and qcow2
support compression. The
compression 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 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 performance.
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).
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 reading blocks input blocks.
The size syntax is similar to dd(1)’s size syntax.
Give information about the disk image filename. Use it in
particular 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. The command can output in the format ofmt
which is either human
or json
.
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
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 allocates 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 identify 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 format 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:
data
;
if false, the sectors are either unallocated or stored as optimized
all-zero clusters);
zero
);
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.
Calculate the file size required for a new image. This information can be used
to size logical volumes or SAN LUNs appropriately for the image that will be
placed in them. The values reported are guaranteed to be large enough to fit
the image. The command can output in the format ofmt which is either
human
or json
.
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 snapshot_param.
The following fields are reported:
required size: 524288 fully allocated size:<PHONE_NUMBER>
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.
List, apply, create or delete snapshots in image filename.
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).
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:
This is the default mode and performs a real rebase operation. 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 between 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, comparable to converting an image. It only works if the old backing file still exists.
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 accessible old backing file, i.e. you can use it to fix an image whose backing file has already been moved/renamed.
You can use rebase
to perform a “diff” operation on two
disk images. 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
template 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.
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 allocated file systems and partition sizes accordingly. Failure to do so will result in data loss!
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.
Amends the image format specific options for the image file filename. Not all file formats support this operation.
qemu-nbd
Invocationqemu-nbd
[OPTION]... filenameqemu-nbd
-d dev
Export a QEMU disk image using the NBD protocol.
filename is a disk image filename, or a set of block driver options if –image-opts is specified.
dev is an NBD device.
Define a new instance of the type object class identified by id.
See the qemu(1)
manual page for full details of the properties
supported. The common object types that it makes sense to define are the
secret
object, which is used to supply passwords and/or encryption
keys, and the tls-creds
object, which is used to supply TLS
credentials for the qemu-nbd server.
The TCP port to listen on (default ‘10809’)
The offset into the image
The interface to bind to (default ‘<IP_ADDRESS>’)
Use a unix socket with path path
Treat filename as a set of image options, instead of a plain
filename. If this flag is specified, the -f flag should
not be used, instead the ’format=
’ option should be set.
Force the use of the block driver for format fmt instead of auto-detecting
Export the disk as read-only
Only expose partition num
Use filename as an external snapshot, create a temporary file with backing_file=filename, redirect the write to the temporary one
Load an internal snapshot inside filename and export it as an read-only device, snapshot_param format is ’snapshot.id=[ID],snapshot.name=[NAME]’ or ’[ID_OR_NAME]’
The cache mode to be used with the file. See the documentation of
the emulator’s -drive cache=...
option for allowed values.
Set the asynchronous I/O mode between ‘threads’ (the default) and ‘native’ (Linux only).
Control whether discard (also known as trim or unmap) requests are ignored or passed to the filesystem. discard is one of ‘ignore’ (or ‘off’), ‘unmap’ (or ‘on’). The default is ‘ignore’.
Control the automatic conversion of plain zero writes by the OS to driver-specific optimized zero write commands. detect-zeroes is one of ‘off’, ‘on’ or ‘unmap’. ‘unmap’ converts a zero write to an unmap operation and can only be used if discard is set to ‘unmap’. The default is ‘off’.
Connect filename to NBD device dev
Disconnect the device dev
Allow up to num clients to share the device (default ‘1’)
Don’t exit on the last connection
Set the NBD volume export name. This switches the server to use the new style NBD protocol negotiation
Set the NBD volume export description, as a human-readable string. Requires the use of -x
Enable mandatory TLS encryption for the server by setting the ID of the TLS credentials object previously created with the –object option.
Fork off the server process and exit the parent once the server is running.
Display extra debugging information
Display this help and exit
Display version information and exit
Specify tracing options.
Immediately enable events matching pattern. 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. To specify multiple events or patterns, specify the -trace option multiple times.
Use -trace help
to print a list of names of trace points.
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.
Log output traces to file. This option is only available if QEMU has been compiled with the simple tracing backend.
QEMU supports many image file formats that can be used with VMs as well as with
any of the tools (like qemu-img
). This includes the preferred formats
raw and qcow2 as well as formats that are supported for compatibility with
older QEMU versions or other hypervisors.
Depending on the image format, different options can be passed to
qemu-img create
and qemu-img convert
using the -o
option.
This section describes each format and the options that are supported for it.
Raw disk image format. 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
).
falloc
mode preallocates space for image by calling posix_fallocate().
full
mode preallocates space for image by writing zeros to underlying
storage.
QEMU image format, the most versatile format. Use it to have smaller images (useful if your filesystem does not supports holes, for example on Windows), 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
This option is deprecated and equivalent to encrypt.format=aes
encrypt.format
If this is set to luks
, it requests that the qcow2 payload (not
qcow2 header) be encrypted using the LUKS format. The passphrase to
use to unlock the LUKS key slot is given by the encrypt.key-secret
parameter. LUKS encryption parameters can be tuned with the other
encrypt.*
parameters.
If this is set to aes
, the image is encrypted with 128-bit AES-CBC.
The encryption key is given by the encrypt.key-secret
parameter.
This encryption format is considered to be flawed by modern cryptography
standards, suffering from a number of design problems:
The use of this is no longer supported in system emulators. Support only
remains in the command line utilities, for the purposes of data liberation
and interoperability with old versions of QEMU. The luks
format
should be used instead.
encrypt.key-secret
Provides the ID of a secret
object that contains the passphrase
(encrypt.format=luks
) or encryption key (encrypt.format=aes
).
encrypt.cipher-alg
Name of the cipher algorithm and key length. Currently defaults
to aes-256
. Only used when encrypt.format=luks
.
encrypt.cipher-mode
Name of the encryption mode to use. Currently defaults to xts
.
Only used when encrypt.format=luks
.
encrypt.ivgen-alg
Name of the initialization vector generator algorithm. Currently defaults
to plain64
. Only used when encrypt.format=luks
.
encrypt.ivgen-hash-alg
Name of the hash algorithm to use with the initialization vector generator
(if required). Defaults to sha256
. Only used when encrypt.format=luks
.
encrypt.hash-alg
Name of the hash algorithm to use for PBKDF algorithm
Defaults to sha256
. Only used when encrypt.format=luks
.
encrypt.iter-time
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
Defaults to 2000
. Only used when encrypt.format=luks
.
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 options 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 improving 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
tables 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 systems.
Btrfs has low performance when hosting a VM image file, even more when the guest on the VM also using btrfs as file system. Turning off COW is a way to mitigate this bad performance. Generally there are two ways to turn off COW on btrfs: a) Disable it by mounting with nodatacow, then all newly created files will be NOCOW. b) 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).
Old QEMU image format with support for backing files and compact image files (when your filesystem or transport medium does not support holes).
When converting QED images to qcow2, you might want to consider using the
lazy_refcounts=on
option to get a more QED-like behaviour.
Supported options:
backing_file
File name of a base image (see create subcommand).
backing_fmt
Image file format of backing file (optional). Useful if the format cannot be autodetected because it has no header, like some vhd/vpc files.
cluster_size
Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller cluster sizes can improve the image file size whereas larger cluster sizes generally provide better performance.
table_size
Changes the number of clusters per L1/L2 table (must be power-of-2 between 1 and 16). There is normally no need to change this value but this option can be used for performance benchmarking.
Old QEMU image format with support for backing files, compact image files, encryption and compression.
Supported options:
backing_file
File name of a base image (see create subcommand)
encryption
This option is deprecated and equivalent to encrypt.format=aes
encrypt.format
If this is set to aes
, the image is encrypted with 128-bit AES-CBC.
The encryption key is given by the encrypt.key-secret
parameter.
This encryption format is considered to be flawed by modern cryptography
standards, suffering from a number of design problems enumerated previously
against the qcow2
image format.
The use of this is no longer supported in system emulators. Support only remains in the command line utilities, for the purposes of data liberation and interoperability with old versions of QEMU.
Users requiring native encryption should use the qcow2
format
instead with encrypt.format=luks
.
encrypt.key-secret
Provides the ID of a secret
object that contains the encryption
key (encrypt.format=aes
).
LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
Supported options:
key-secret
Provides the ID of a secret
object that contains the passphrase.
cipher-alg
Name of the cipher algorithm and key length. Currently defaults
to aes-256
.
cipher-mode
Name of the encryption mode to use. Currently defaults to xts
.
ivgen-alg
Name of the initialization vector generator algorithm. Currently defaults
to plain64
.
ivgen-hash-alg
Name of the hash algorithm to use with the initialization vector generator
(if required). Defaults to sha256
.
hash-alg
Name of the hash algorithm to use for PBKDF algorithm
Defaults to sha256
.
iter-time
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
Defaults to 2000
.
VirtualBox 1.1 compatible image format. Supported options:
static
If this option is set to on
, the image is created with metadata
preallocation.
VMware 3 and 4 compatible image format.
Supported options:
backing_file
File name of a base image (see create subcommand).
compat6
Create a VMDK version 6 image (instead of version 4)
hwversion
Specify vmdk virtual hardware version. Compat6 flag cannot be enabled if hwversion is specified.
subformat
Specifies which VMDK subformat to use. Valid options are
monolithicSparse
(default),
monolithicFlat
,
twoGbMaxExtentSparse
,
twoGbMaxExtentFlat
and
streamOptimized
.
VirtualPC compatible image format (VHD). Supported options:
subformat
Specifies which VHD subformat to use. Valid options are
dynamic
(default) and fixed
.
Hyper-V compatible image format (VHDX). Supported options:
subformat
Specifies which VHDX subformat to use. Valid options are
dynamic
(default) and fixed
.
block_state_zero
Force use of payload blocks of type ’ZERO’. Can be set to on
(default)
or off
. When set to off
, new blocks will be created as
PAYLOAD_BLOCK_NOT_PRESENT
, which means parsers are free to return
arbitrary data for those blocks. Do not set to off
when using
qemu-img convert
with subformat=dynamic
.
block_size
Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on image size.
log_size
Log size; min 1 MB.
More disk image file formats are supported in a read-only mode.
Bochs images of growing
type.
Linux Compressed Loop image, useful only to reuse directly compressed CD-ROM images present for example in the Knoppix CD-ROMs.
Apple disk image.
Parallels disk image format.
In addition to disk image files, QEMU can directly access host devices. We describe here the usage for QEMU version >= 0.8.3.
On Linux, you can directly use the host device filename instead of a disk image filename provided you have enough privileges to access it. For example, use /dev/cdrom to access to the CDROM.
CD
You can specify a CDROM device even if no CDROM is loaded. QEMU has specific code to detect CDROM insertion or removal. CDROM ejection by the guest OS is supported. Currently only data CDs are supported.
Floppy
You can specify a floppy device even if no floppy is loaded. Floppy removal is currently not detected accurately (if you change floppy without doing floppy access while the floppy is not loaded, the guest OS will think that the same floppy is loaded). Use of the host’s floppy device is deprecated, and support for it will be removed in a future release.
Hard disks
Hard disks can be used. Normally you must specify the whole disk (/dev/hdb instead of /dev/hdb1) so that the guest OS can see it as a partitioned disk. WARNING: unless you know what you do, it is better to only make READ-ONLY accesses to the hard disk otherwise you may corrupt your host data (use the -snapshot command line option or modify the device permissions accordingly).
CD
The preferred syntax is the drive letter (e.g. d:). The alternate syntax \\.\d: is supported. /dev/cdrom is supported as an alias to the first CDROM drive.
Currently there is no specific code to handle removable media, so it
is better to use the change
or eject
monitor commands to
change or eject media.
Hard disks
Hard disks can be used with the syntax: \\.\PhysicalDriveN where N is the drive number (0 is the first hard disk).
WARNING: unless you know what you do, it is better to only make READ-ONLY accesses to the hard disk otherwise you may corrupt your host data (use the -snapshot command line so that the modifications are written in a temporary file).
/dev/cdrom is an alias to the first CDROM.
Currently there is no specific code to handle removable media, so it
is better to use the change
or eject
monitor commands to
change or eject media.
QEMU can automatically create a virtual FAT disk image from a directory tree. In order to use it, just type:
qemu-system-i386 linux.img -hdb fat:/my_directory
Then you access access to all the files in the /my_directory directory without having to copy them in a disk image or to export them via SAMBA or NFS. The default access is read-only.
Floppies can be emulated with the :floppy:
option:
qemu-system-i386 linux.img -fda fat:floppy:/my_directory
A read/write support is available for testing (beta stage) with the
:rw:
option:
qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
What you should never do:
QEMU can access directly to block device exported using the Network Block Device protocol.
qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
If the NBD server is located on the same host, you can use an unix socket instead of an inet socket:
qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
In this case, the block device must be exported using qemu-nbd:
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
The use of qemu-nbd allows sharing of a disk between several guests:
qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
and then you can use it with two guests:
qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU’s own embedded NBD server), you must specify an export name in the URI:
qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is also available. Here are some example of the older syntax:
qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024 qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
Sheepdog is a distributed storage system for QEMU. It provides highly available block level storage volumes that can be attached to QEMU-based virtual machines.
You can create a Sheepdog disk image with the command:
qemu-img create sheepdog:///image size
where image is the Sheepdog image name and size is its size.
To import the existing filename to Sheepdog, you can use a convert command.
qemu-img convert filename sheepdog:///image
You can boot from the Sheepdog disk image with the command:
qemu-system-i386 sheepdog:///image
You can also create a snapshot of the Sheepdog image like qcow2.
qemu-img snapshot -c tag sheepdog:///image
where tag is a tag name of the newly created snapshot.
To boot from the Sheepdog snapshot, specify the tag name of the snapshot.
qemu-system-i386 sheepdog:///image#tag
You can create a cloned image from the existing snapshot.
qemu-img create -b sheepdog:///base#tag sheepdog:///image
where base is a image name of the source snapshot and tag is its tag name.
You can use an unix socket instead of an inet socket:
qemu-system-i386 sheepdog+unix:///image?socket=path
If the Sheepdog daemon doesn’t run on the local host, you need to specify one of the Sheepdog servers to connect to.
qemu-img create sheepdog://hostname:port/image size qemu-system-i386 sheepdog://hostname:port/image
iSCSI is a popular protocol used to access SCSI devices across a computer network.
There are two different ways iSCSI devices can be used by QEMU.
The first method is to mount the iSCSI LUN on the host, and make it appear as any other ordinary SCSI device on the host and then to access this device as a /dev/sd device from QEMU. How to do this differs between host OSes.
The second method involves using the iSCSI initiator that is built into QEMU. This provides a mechanism that works the same way regardless of which host OS you are running QEMU on. This section will describe this second method of using iSCSI together with QEMU.
In QEMU, iSCSI devices are described using special iSCSI URLs
URL syntax: iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn-name>/<lun>
Username and password are optional and only used if your target is set up using CHAP authentication for access control. Alternatively the username and password can also be set via environment variables to have these not show up in the process list
export LIBISCSI_CHAP_USERNAME=<username> export LIBISCSI_CHAP_PASSWORD=<password> iscsi://<host>/<target-iqn-name>/<lun>
Various session related parameters can be set via special options, either in a configuration file provided via ’-readconfig’ or directly on the command line.
If the initiator-name is not specified qemu will use a default name of ’iqn.2008-11.org.linux-kvm[:<uuid>’] where <uuid> is the UUID of the virtual machine. If the UUID is not specified qemu will use ’iqn.2008-11.org.linux-kvm[:<name>’] where <name> is the name of the virtual machine.
Setting a specific initiator name to use when logging in to the target -iscsi initiator-name=iqn.qemu.test:my-initiator
Controlling which type of header digest to negotiate with the target -iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
These can also be set via a configuration file
[iscsi] user = "CHAP username" password = "CHAP password" initiator-name = "iqn.qemu.test:my-initiator" # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE header-digest = "CRC32C"
Setting the target name allows different options for different targets
[iscsi "iqn.target.name"] user = "CHAP username" password = "CHAP password" initiator-name = "iqn.qemu.test:my-initiator" # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE header-digest = "CRC32C"
Howto use a configuration file to set iSCSI configuration options:
cat >iscsi.conf <<EOF [iscsi] user = "me" password = "my password" initiator-name = "iqn.qemu.test:my-initiator" header-digest = "CRC32C" EOF qemu-system-i386 -drive file=iscsi://<IP_ADDRESS>/iqn.qemu.test/1 \ -readconfig iscsi.conf
Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
This example shows how to set up an iSCSI target with one CDROM and one DISK using the Linux STGT software target.
You can boot from the GlusterFS disk image with the command:
URI: qemu-system-x86_64 -drive file=gluster[+type]://[host[:port]]/volume/path [?socket=...][,file.debug=9][,file.logfile=...] JSON: qemu-system-x86_64 'json:{"driver":"qcow2", "file":{"driver":"gluster", "volume":"testvol","path":"a.img","debug":9,"logfile":"...", "server":[{"type":"tcp","host":"...","port":"..."}, {"type":"unix","socket":"..."}]}}'
gluster is the protocol.
type specifies the transport type used to connect to gluster management daemon (glusterd). Valid transport types are tcp and unix. In the URI form, if a transport type isn’t specified, then tcp type is assumed.
host specifies the server where the volume file specification for the given volume resides. This can be either a hostname or an ipv4 address. If transport type is unix, then host field should not be specified. Instead socket field needs to be populated with the path to unix domain socket.
port is the port number on which glusterd is listening. This is optional and if not specified, it defaults to port 24007. If the transport type is unix, then port should not be specified.
volume is the name of the gluster volume which contains the disk image.
path is the path to the actual disk image that resides on gluster volume.
debug is the logging level of the gluster protocol driver. Debug levels are 0-9, with 9 being the most verbose, and 0 representing no debugging output. The default level is 4. The current logging levels defined in the gluster source are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning, 6 - Notice, 7 - Info, 8 - Debug, 9 - Trace
logfile is a commandline option to mention log file path which helps in logging to the specified file and also help in persisting the gfapi logs. The default is stderr.
You can create a GlusterFS disk image with the command:
qemu-img create gluster://host/volume/path size
Examples
qemu-system-x86_64 -drive file=gluster://<IP_ADDRESS>/testvol/a.img qemu-system-x86_64 -drive file=gluster+tcp://<IP_ADDRESS>/testvol/a.img qemu-system-x86_64 -drive file=gluster+tcp://<IP_ADDRESS>:24007/testvol/dir/a.img qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket qemu-system-x86_64 -drive file=gluster+rdma://<IP_ADDRESS>:24007/testvol/a.img qemu-system-x86_64 -drive file=gluster://<IP_ADDRESS>/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log qemu-system-x86_64 'json:{"driver":"qcow2", "file":{"driver":"gluster", "volume":"testvol","path":"a.img", "debug":9,"logfile":"/var/log/qemu-gluster.log", "server":[{"type":"tcp","host":"<IP_ADDRESS>","port":24007}, {"type":"unix","socket":"/var/run/glusterd.socket"}]}}' qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, file.debug=9,file.logfile=/var/log/qemu-gluster.log, file.server.0.type=tcp,file.server.0.host=<IP_ADDRESS>,file.server.0.port=24007, file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
You can access disk images located on a remote ssh server by using the ssh protocol:
qemu-system-x86_64 -drive file=ssh://[user@]server[:port]/path[?host_key_check=host_key_check]
Alternative syntax using properties:
qemu-system-x86_64 -drive file.driver=ssh[,file.user=user],file.host=server[,file.port=port],file.path=path[,file.host_key_check=host_key_check]
ssh is the protocol.
user is the remote user. If not specified, then the local username is tried.
server specifies the remote ssh server. Any ssh server can be used, but it must implement the sftp-server protocol. Most Unix/Linux systems should work without requiring any extra configuration.
port is the port number on which sshd is listening. By default the standard ssh port (22) is used.
path is the path to the disk image.
The optional host_key_check parameter controls how the remote
host’s key is checked. The default is yes
which means to use
the local .ssh/known_hosts file. Setting this to no
turns off known-hosts checking. Or you can check that the host key
matches a specific fingerprint:
host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8
(sha1:
can also be used as a prefix, but note that OpenSSH
tools only use MD5 to print fingerprints).
Currently authentication must be done using ssh-agent. Other authentication methods may be supported in future.
Note: Many ssh servers do not support an fsync
-style operation.
The ssh driver cannot guarantee that disk flush requests are
obeyed, and this causes a risk of disk corruption if the remote
server or network goes down during writes. The driver will
print a warning when fsync
is not supported:
warning: ssh server ssh.example.com:22
does not support fsync
With sufficiently new versions of libssh2 and OpenSSH, fsync
is
supported.
QEMU can simulate several network cards (PCI or ISA cards on the PC target) and can connect them to an arbitrary number of Virtual Local Area Networks (VLANs). Host TAP devices can be connected to any QEMU VLAN. VLAN can be connected between separate instances of QEMU to simulate large networks. For simpler usage, a non privileged user mode network stack can replace the TAP device to have a basic network connection.
QEMU simulates several VLANs. A VLAN can be symbolised as a virtual connection between several network devices. These devices can be for example QEMU virtual Ethernet cards or virtual Host ethernet devices (TAP devices).
This is the standard way to connect QEMU to a real network. QEMU adds
a virtual network device on your host (called tapN
), and you
can then configure it as if it was a real ethernet card.
As an example, you can download the linux-test-xxx.tar.gz
archive and copy the script qemu-ifup in /etc and
configure properly sudo
so that the command ifconfig
contained in qemu-ifup can be executed as root. You must verify
that your host kernel supports the TAP network interfaces: the
device /dev/net/tun must be present.
See sec_invocation to have examples of command lines using the TAP network interfaces.
There is a virtual ethernet driver for Windows 2000/XP systems, called TAP-Win32. But it is not included in standard QEMU for Windows, so you will need to get it separately. It is part of OpenVPN package, so download OpenVPN from : http://openvpn.net/.
By using the option -net user (default configuration if no -net option is specified), QEMU uses a completely user mode network stack (you don’t need root privilege to use the virtual network). The virtual network configuration is the following:
QEMU VLAN <------> Firewall/DHCP server <-----> Internet | (<IP_ADDRESS>) | ----> DNS server (<IP_ADDRESS>) | ----> SMB server (<IP_ADDRESS>)
The QEMU VM behaves as if it was behind a firewall which blocks all incoming connections. You can use a DHCP client to automatically configure the network in the QEMU VM. The DHCP server assign addresses to the hosts starting from <IP_ADDRESS>.
In order to check that the user mode network is working, you can ping the address <IP_ADDRESS> and verify that you got an address in the range 10.0.2.x from the QEMU virtual DHCP server.
Note that ICMP traffic in general does not work with user mode networking.
ping
, aka. ICMP echo, to the local router (<IP_ADDRESS>) shall work,
however. If you’re using QEMU on Linux >= 3.0, it can use unprivileged ICMP
ping sockets to allow ping
to the Internet. The host admin has to set
the ping_group_range in order to grant access to those sockets. To allow ping
for GID 100 (usually users group):
echo 100 100 > /proc/sys/net/ipv4/ping_group_range
When using the built-in TFTP server, the router is also the TFTP server.
When using the '-netdev user,hostfwd=...' option, TCP or UDP connections can be redirected from the host to the guest. It allows for example to redirect X11, telnet or SSH connections.
Using the -net socket option, it is possible to make VLANs that span several QEMU instances. See sec_invocation to have a basic example.
On Linux hosts, a shared memory device is available. The basic syntax is:
qemu-system-x86_64 -device ivshmem-plain,memdev=hostmem
where hostmem names a host memory backend. For a POSIX shared memory backend, use something like
-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=hostmem
If desired, interrupts can be sent between guest VMs accessing the same shared memory region. Interrupt support requires using a shared memory server and using a chardev socket to connect to it. The code for the shared memory server is qemu.git/contrib/ivshmem-server. An example syntax when using the shared memory server is:
# First start the ivshmem server once and for all ivshmem-server -p pidfile -S path -m shm-name -l shm-size -n vectors # Then start your qemu instances with matching arguments qemu-system-x86_64 -device ivshmem-doorbell,vectors=vectors,chardev=id -chardev socket,path=path,id=id
When using the server, the guest will be assigned a VM ID (>=0) that allows guests using the same server to communicate via interrupts. Guests can read their VM ID from a device register (see ivshmem-spec.txt).
With device property master=on, the guest will copy the shared memory on migration to the destination host. With master=off, the guest will not be able to migrate with the device attached. In the latter case, the device should be detached and then reattached after migration using the PCI hotplug support.
At most one of the devices sharing the same memory can be master. The master must complete migration before you plug back the other devices.
Instead of specifying the <shm size> using POSIX shm, you may specify a memory backend that has hugepage support:
qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1 -device ivshmem-plain,memdev=mb1
ivshmem-server also supports hugepages mount points with the -m memory path argument.
This section explains how to launch a Linux kernel inside QEMU without having to make a full bootable image. It is very useful for fast Linux kernel testing.
The syntax is:
qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
Use -kernel to provide the Linux kernel image and -append to give the kernel command line arguments. The -initrd option can be used to provide an INITRD image.
When using the direct Linux boot, a disk image for the first hard disk hda is required because its boot sector is used to launch the Linux kernel.
If you do not need graphical output, you can disable it and redirect the virtual serial port and the QEMU monitor to the console with the -nographic option. The typical command line is:
qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ -append "root=/dev/hda console=ttyS0" -nographic
Use Ctrl-a c to switch between the serial console and the monitor (see pcsys_keys).
QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can plug virtual USB devices or real host USB devices (only works with certain host operating systems). QEMU will automatically create and connect virtual USB hubs as necessary to connect multiple USB devices.
USB devices can be connected with the -device usb-... command line
option or the device_add
monitor command. Available devices are:
usb-mouse
Virtual Mouse. This will override the PS/2 mouse emulation when activated.
usb-tablet
Pointer device that uses absolute coordinates (like a touchscreen). This means QEMU is able to report the mouse position without having to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
usb-storage,drive=drive_id
Mass storage device backed by drive_id (see disk_images)
usb-uas
USB attached SCSI device, see usb-storage.txt for details
usb-bot
Bulk-only transport storage device, see usb-storage.txt for details here, too
usb-mtp,x-root=dir
Media transfer protocol device, using dir as root of the file tree that is presented to the guest.
usb-host,hostbus=bus,hostaddr=addr
Pass through the host device identified by bus and addr
usb-host,vendorid=vendor,productid=product
Pass through the host device identified by vendor and product ID
usb-wacom-tablet
Virtual Wacom PenPartner tablet. This device is similar to the tablet
above but it can be used with the tslib library because in addition to touch
coordinates it reports touch pressure.
usb-kbd
Standard USB keyboard. Will override the PS/2 keyboard (if present).
usb-serial,chardev=id
Serial converter. This emulates an FTDI FT232BM chip connected to host character device id.
usb-braille,chardev=id
Braille device. This will use BrlAPI to display the braille output on a real or fake device referenced by id.
usb-net[,netdev=id]
Network adapter that supports CDC ethernet and RNDIS protocols. id
specifies a netdev defined with -netdev …,id=id
.
For instance, user-mode networking can be used with
qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
usb-ccid
Smartcard reader device
usb-audio
USB audio device
usb-bt-dongle
Bluetooth dongle for the transport layer of HCI. It is connected to HCI
scatternet 0 by default (corresponds to -bt hci,vlan=0
).
Note that the syntax for the -device usb-bt-dongle
option is not as
useful yet as it was with the legacy -usbdevice
option. So to
configure an USB bluetooth device, you might need to use
"-usbdevice bt
[:hci-type]" instead. This configures a
bluetooth dongle whose type is specified in the same format as with
the -bt hci option, see allowed HCI types. If
no type is given, the HCI logic corresponds to -bt hci,vlan=0
.
This USB device implements the USB Transport Layer of HCI. Example
usage:
qemu-system-i386
[...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
WARNING: this is an experimental feature. QEMU will slow down when using it. USB devices requiring real time streaming (i.e. USB Video Cameras) are not supported yet.
ls /proc/bus/usb 001 devices drivers
chown -R myuid /proc/bus/usb
info usbhost Device 1.2, speed 480 Mb/s Class 00: USB device 1234:5678, USB DISK
You should see the list of the devices you can use (Never try to use hubs, it won’t work).
device_add usb-host,vendorid=0x1234,productid=0x5678
Normally the guest OS should report that a new USB device is plugged. You can use the option -device usb-host,... to do the same.
When relaunching QEMU, you may have to unplug and plug again the USB device to make it work again (this is a bug).
The VNC server capability provides access to the graphical console of the guest VM across the network. This has a number of security considerations depending on the deployment scenarios.
The simplest VNC server setup does not include any form of authentication. For this setup it is recommended to restrict it to listen on a UNIX domain socket only. For example
qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
This ensures that only users on local box with read/write access to that path can access the VNC server. To securely access the VNC server from a remote machine, a combination of netcat+ssh can be used to provide a secure tunnel.
The VNC protocol has limited support for password based authentication. Since
the protocol limits passwords to 8 characters it should not be considered
to provide high security. The password can be fairly easily brute-forced by
a client making repeat connections. For this reason, a VNC server using password
authentication should be restricted to only listen on the loopback interface
or UNIX domain sockets. Password authentication is not supported when operating
in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
authentication is requested with the password
option, and then once QEMU
is running the password is set with the monitor. Until the monitor is used to
set the password all clients will be rejected.
qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio (qemu) change vnc password Password: ******** (qemu)
The QEMU VNC server also implements the VeNCrypt extension allowing use of TLS for encryption of the session, and x509 certificates for authentication. The use of x509 certificates is strongly recommended, because TLS on its own is susceptible to man-in-the-middle attacks. Basic x509 certificate support provides a secure session, but no authentication. This allows any client to connect, and provides an encrypted session.
qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
In the above example /etc/pki/qemu
should contain at least three files,
ca-cert.pem
, server-cert.pem
and server-key.pem
. Unprivileged
users will want to use a private directory, for example $HOME/.pki/qemu
.
NB the server-key.pem
file should be protected with file mode 0600 to
only be readable by the user owning it.
Certificates can also provide a means to authenticate the client connecting. The server will request that the client provide a certificate, which it will then validate against the CA certificate. This is a good choice if deploying in an environment with a private internal certificate authority.
qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
Finally, the previous method can be combined with VNC password authentication to provide two layers of authentication for clients.
qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio (qemu) change vnc password Password: ******** (qemu)
The SASL authentication method is a VNC extension, that provides an easily extendable, pluggable authentication method. This allows for integration with a wide range of authentication mechanisms, such as PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more. The strength of the authentication depends on the exact mechanism configured. If the chosen mechanism also provides a SSF layer, then it will encrypt the datastream as well.
Refer to the later docs on how to choose the exact SASL mechanism used for authentication, but assuming use of one supporting SSF, then QEMU can be launched with:
qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
If the desired SASL authentication mechanism does not supported SSF layers, then it is strongly advised to run it in combination with TLS and x509 certificates. This provides securely encrypted data stream, avoiding risk of compromising of the security credentials. This can be enabled, by combining the ’sasl’ option with the aforementioned TLS + x509 options:
qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
The GNU TLS packages provides a command called certtool
which can
be used to generate certificates and keys in PEM format. At a minimum it
is necessary to setup a certificate authority, and issue certificates to
each server. If using certificates for authentication, then each client
will also need to be issued a certificate. The recommendation is for the
server to keep its certificates in either /etc/pki/qemu
or for
unprivileged users in $HOME/.pki/qemu
.
This step only needs to be performed once per organization / organizational unit. First the CA needs a private key. This key must be kept VERY secret and secure. If this key is compromised the entire trust chain of the certificates issued with it is lost.
# certtool --generate-privkey > ca-key.pem
A CA needs to have a public certificate. For simplicity it can be a self-signed certificate, or one issue by a commercial certificate issuing authority. To generate a self-signed certificate requires one core piece of information, the name of the organization.
# cat > ca.info <<EOF cn = Name of your organization ca cert_signing_key EOF # certtool --generate-self-signed \ --load-privkey ca-key.pem --template ca.info \ --outfile ca-cert.pem
The ca-cert.pem
file should be copied to all servers and clients wishing to utilize
TLS support in the VNC server. The ca-key.pem
must not be disclosed/copied at all.
Each server (or host) needs to be issued with a key and certificate. When connecting the certificate is sent to the client which validates it against the CA certificate. The core piece of information for a server certificate is the hostname. This should be the fully qualified hostname that the client will connect with, since the client will typically also verify the hostname in the certificate. On the host holding the secure CA private key:
# cat > server.info <<EOF organization = Name of your organization cn = server.foo.example.com tls_www_server encryption_key signing_key EOF # certtool --generate-privkey > server-key.pem # certtool --generate-certificate \ --load-ca-certificate ca-cert.pem \ --load-ca-privkey ca-key.pem \ --load-privkey server-key.pem \ --template server.info \ --outfile server-cert.pem
The server-key.pem
and server-cert.pem
files should now be securely copied
to the server for which they were generated. The server-key.pem
is security
sensitive and should be kept protected with file mode 0600 to prevent disclosure.
If the QEMU VNC server is to use the x509verify
option to validate client
certificates as its authentication mechanism, each client also needs to be issued
a certificate. The client certificate contains enough metadata to uniquely identify
the client, typically organization, state, city, building, etc. On the host holding
the secure CA private key:
# cat > client.info <<EOF country = GB state = London locality = London organization = Name of your organization cn = client.foo.example.com tls_www_client encryption_key signing_key EOF # certtool --generate-privkey > client-key.pem # certtool --generate-certificate \ --load-ca-certificate ca-cert.pem \ --load-ca-privkey ca-key.pem \ --load-privkey client-key.pem \ --template client.info \ --outfile client-cert.pem
The client-key.pem
and client-cert.pem
files should now be securely
copied to the client for which they were generated.
The following documentation assumes use of the Cyrus SASL implementation on a Linux host, but the principals should apply to any other SASL impl. When SASL is enabled, the mechanism configuration will be loaded from system default SASL service config /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user, an environment variable SASL_CONF_PATH can be used to make it search alternate locations for the service config.
If the TLS option is enabled for VNC, then it will provide session encryption, otherwise the SASL mechanism will have to provide encryption. In the latter case the list of possible plugins that can be used is drastically reduced. In fact only the GSSAPI SASL mechanism provides an acceptable level of security by modern standards. Previous versions of QEMU referred to the DIGEST-MD5 mechanism, however, it has multiple serious flaws described in detail in RFC 6331 and thus should never be used any more. The SCRAM-SHA-1 mechanism provides a simple username/password auth facility similar to DIGEST-MD5, but does not support session encryption, so can only be used in combination with TLS.
When not using TLS the recommended configuration is
mech_list: gssapi keytab: /etc/qemu/krb5.tab
This says to use the ’GSSAPI’ mechanism with the Kerberos v5 protocol, with the server principal stored in /etc/qemu/krb5.tab. For this to work the administrator of your KDC must generate a Kerberos principal for the server, with a name of<EMAIL_ADDRESS>replacing ’somehost.example.com’ with the fully qualified host name of the machine running QEMU, and ’EXAMPLE.COM’ with the Kerberos Realm.
When using TLS, if username+password authentication is desired, then a reasonable configuration is
mech_list: scram-sha-1 sasldb_path: /etc/qemu/passwd.db
The saslpasswd2 program can be used to populate the passwd.db file with accounts.
Other SASL configurations will be left as an exercise for the reader. Note that all mechanisms except GSSAPI, should be combined with use of TLS to ensure a secure data channel.
QEMU has a primitive support to work with gdb, so that you can do ’Ctrl-C’ while the virtual machine is running and inspect its state.
In order to use gdb, launch QEMU with the ’-s’ option. It will wait for a gdb connection:
qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ -append "root=/dev/hda" Connected to host network interface: tun0 Waiting gdb connection on port 1234
Then launch gdb on the ’vmlinux’ executable:
> gdb vmlinux
In gdb, connect to QEMU:
(gdb) target remote localhost:1234
Then you can use gdb normally. For example, type ’c’ to launch the kernel:
(gdb) c
Here are some useful tips in order to use gdb on system code:
info reg
to display all the CPU registers.
x/10i $eip
to display the code at the PC position.
set architecture i8086
to dump 16 bit code. Then use
x/10i $cs*16+$eip
to dump the code at the PC position.
Advanced debugging options:
The default single stepping behavior is step with the IRQs and timer service routines off. It is set this way because when gdb executes a single step it expects to advance beyond the current instruction. With the IRQs and timer service routines on, a single step might jump into the one of the interrupt or exception vectors instead of executing the current instruction. This means you may hit the same breakpoint a number of times before executing the instruction gdb wants to have executed. Because there are rare circumstances where you want to single step into an interrupt vector the behavior can be controlled from GDB. There are three commands you can query and set the single step behavior:
maintenance packet qqemu.sstepbits
This will display the MASK bits used to control the single stepping IE:
(gdb) maintenance packet qqemu.sstepbits sending: "qqemu.sstepbits" received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
maintenance packet qqemu.sstep
This will display the current value of the mask used when single stepping IE:
(gdb) maintenance packet qqemu.sstep sending: "qqemu.sstep" received: "0x7"
maintenance packet Qqemu.sstep=HEX_VALUE
This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
(gdb) maintenance packet Qqemu.sstep=0x5 sending: "qemu.sstep=0x5" received: "OK"
To have access to SVGA graphic modes under X11, use the vesa
or
the cirrus
X11 driver. For optimal performances, use 16 bit
color depth in the guest and the host OS.
When using a 2.6 guest Linux kernel, you should add the option
clock=pit
on the kernel command line because the 2.6 Linux
kernels make very strict real time clock checks by default that QEMU
cannot simulate exactly.
When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is not activated because QEMU is slower with this patch. The QEMU Accelerator Module is also much slower in this case. Earlier Fedora Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this patch by default. Newer kernels don’t have it.
If you have a slow host, using Windows 95 is better as it gives the best speed. Windows 2000 is also a good choice.
QEMU emulates a Cirrus Logic GD5446 Video card. All Windows versions starting from Windows 95 should recognize and use this graphic card. For optimal performances, use 16 bit color depth in the guest and the host OS.
If you are using Windows XP as guest OS and if you want to use high resolution modes which the Cirrus Logic BIOS does not support (i.e. >= 1280x1024x16), then you should use the VESA VBE virtual graphic card (option -std-vga).
Windows 9x does not correctly use the CPU HLT instruction. The result is that it takes host CPU cycles even when idle. You can install the utility from http://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip to solve this problem. Note that no such tool is needed for NT, 2000 or XP.
Windows 2000 has a bug which gives a disk full problem during its installation. When installing it, use the -win2k-hack QEMU option to enable a specific workaround. After Windows 2000 is installed, you no longer need this option (this option slows down the IDE transfers).
Windows 2000 cannot automatically shutdown in QEMU although Windows 98 can. It comes from the fact that Windows 2000 does not automatically use the APM driver provided by the BIOS.
In order to correct that, do the following (thanks to Struan Bartlett): go to the Control Panel => Add/Remove Hardware & Next => Add/Troubleshoot a device => Add a new device & Next => No, select the hardware from a list & Next => NT Apm/Legacy Support & Next => Next (again) a few times. Now the driver is installed and Windows 2000 now correctly instructs QEMU to shutdown at the appropriate moment.
See sec_invocation about the help of the option '-netdev user,smb=...'.
Some releases of Windows XP install correctly but give a security error when booting:
A problem is preventing Windows from accurately checking the license for this computer. Error code: 0x800703e6.
The workaround is to install a service pack for XP after a boot in safe mode. Then reboot, and the problem should go away. Since there is no network while in safe mode, its recommended to download the full installation of SP1 or SP2 and transfer that via an ISO or using the vvfat block device ("-hdb fat:directory_which_holds_the_SP").
DOS does not correctly use the CPU HLT instruction. The result is that it takes host CPU cycles even when idle. You can install the utility from http://web.archive.org/web/20051222085335/http://www.vmware.com/software/dosidle210.zip to solve this problem.
QEMU is a generic emulator and it emulates many non PC machines. Most of the options are similar to the PC emulator. The differences are mentioned in the following sections.
Use the executable qemu-system-ppc to simulate a complete PREP or PowerMac PowerPC system.
QEMU emulates the following PowerMac peripherals:
QEMU emulates the following PREP peripherals:
QEMU uses the Open Hack’Ware Open Firmware Compatible BIOS available at http://perso.magic.fr/l_indien/OpenHackWare/index.htm.
Since version 0.9.1, QEMU uses OpenBIOS http://www.openbios.org/ for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL v2) portable firmware implementation. The goal is to implement a 100% IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
The following options are specific to the PowerPC emulation:
Set the initial VGA graphic mode. The default is 800x600x32.
Set OpenBIOS variables in NVRAM, for example:
qemu-system-ppc -prom-env 'auto-boot?=false' \ -prom-env 'boot-device=hd:2,\yaboot' \ -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
These variables are not used by Open Hack’Ware.
More information is available at http://perso.magic.fr/l_indien/qemu-ppc/.
Use the executable qemu-system-sparc to simulate the following Sun4m architecture machines:
The emulation is somewhat complete. SMP up to 16 CPUs is supported, but Linux limits the number of usable CPUs to 4.
QEMU emulates the following sun4m peripherals:
The number of peripherals is fixed in the architecture. Maximum memory size depends on the machine type, for SS-5 it is 256MB and for others 2047MB.
Since version 0.8.2, QEMU uses OpenBIOS http://www.openbios.org/. OpenBIOS is a free (GPL v2) portable firmware implementation. The goal is to implement a 100% IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
A sample Linux 2.6 series kernel and ram disk image are available on the QEMU web site. There are still issues with NetBSD and OpenBSD, but most kernel versions work. Please note that currently older Solaris kernels don’t work probably due to interface issues between OpenBIOS and Solaris.
The following options are specific to the Sparc32 emulation:
Set the initial graphics mode. For TCX, the default is 1024x768x8 with the option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option of 1152x900x8 for people who wish to use OBP.
Set OpenBIOS variables in NVRAM, for example:
qemu-system-sparc -prom-env 'auto-boot?=false' \ -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
Set the emulated machine type. Default is SS-5.
Use the executable qemu-system-sparc64 to simulate a Sun4u (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic Niagara (T1) machine. The Sun4u emulator is mostly complete, being able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The Sun4v emulator is still a work in progress.
The Niagara T1 emulator makes use of firmware and OS binaries supplied in the S10image/ directory of the OpenSPARC T1 project http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2 and is able to boot the disk.s10hw2 Solaris image.
qemu-system-sparc64 -M niagara -L /path-to/S10image/ \ -nographic -m 256 \ -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
QEMU emulates the following peripherals:
The following options are specific to the Sparc64 emulation:
Set OpenBIOS variables in NVRAM, for example:
qemu-system-sparc64 -prom-env 'auto-boot?=false'
Set the emulated machine type. The default is sun4u.
Four executables cover simulation of 32 and 64-bit MIPS systems in both endian options, qemu-system-mips, qemu-system-mipsel qemu-system-mips64 and qemu-system-mips64el. Five different machine types are emulated:
The generic emulation is supported by Debian ’Etch’ and is able to install Debian into a virtual disk image. The following devices are emulated:
The Malta emulation supports the following devices:
The ACER Pica emulation supports:
The mipssim pseudo board emulation provides an environment similar to what the proprietary MIPS emulator uses for running Linux. It supports:
The MIPS Magnum R4000 emulation supports:
Use the executable qemu-system-arm to simulate a ARM machine. The ARM Integrator/CP board is emulated with the following devices:
The ARM Versatile baseboard is emulated with the following devices:
Several variants of the ARM RealView baseboard are emulated, including the EB, PB-A8 and PBX-A9. Due to interactions with the bootloader, only certain Linux kernel configurations work out of the box on these boards.
Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET disabled and expect 1024M RAM.
The following devices are emulated:
The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi" and "Terrier") emulation includes the following peripherals:
The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the following elements:
Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48) emulation supports the following elements:
The Luminary Micro Stellaris LM3S811EVB emulation includes the following devices:
The Luminary Micro Stellaris LM3S6965EVB emulation includes the following devices:
The Freecom MusicPal internet radio emulation includes the following elements:
The Siemens SX1 models v1 and v2 (default) basic emulation. The emulation includes the following elements:
A Linux 2.6 test image is available on the QEMU web site. More information is available in the QEMU mailing-list archive.
The following options are specific to the ARM emulation:
Enable semihosting syscall emulation.
On ARM this implements the "Angel" interface.
Note that this allows guest direct access to the host filesystem, so should only be used with trusted guest OS.
Use the executable qemu-system-m68k to simulate a ColdFire machine. The emulator is able to boot a uClinux kernel.
The M5208EVB emulation includes the following devices:
The AN5206 emulation includes the following devices:
The following options are specific to the ColdFire emulation:
Enable semihosting syscall emulation.
On M68K this implements the "ColdFire GDB" interface used by libgloss.
Note that this allows guest direct access to the host filesystem, so should only be used with trusted guest OS.
TODO
TODO
TODO
Two executables cover simulation of both Xtensa endian options, qemu-system-xtensa and qemu-system-xtensaeb. Two different machine types are emulated:
The sim pseudo board emulation provides an environment similar to one provided by the proprietary Tensilica ISS. It supports:
The Avnet LX60/LX110/LX200 emulation supports:
The following options are specific to the Xtensa emulation:
Enable semihosting syscall emulation.
Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select. Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
Note that this allows guest direct access to the host filesystem, so should only be used with trusted guest OS.
qemu-ga
[OPTIONS]
The QEMU Guest Agent is a daemon intended to be run within virtual machines. It allows the hypervisor host to perform various operations in the guest, such as:
qemu-ga will read a system configuration file on startup (located at /etc/qemu/qemu-ga.conf by default), then parse remaining configuration options on the command line. For the same key, the last option wins, but the lists accumulate (see below for configuration file format).
Transport method: one of ‘unix-listen’, ‘virtio-serial’, or ‘isa-serial’ (‘virtio-serial’ is the default).
Device/socket path (the default for virtio-serial is ‘/dev/virtio-ports/org.qemu.guest_agent.0’, the default for isa-serial is ‘/dev/ttyS0’)
Set log file path (default is stderr).
Specify pid file (default is ‘/var/run/qemu-ga.pid’).
Enable fsfreeze hook. Accepts an optional argument that specifies script to run on freeze/thaw. Script will be called with ’freeze’/’thaw’ arguments accordingly (default is ‘/etc/qemu/fsfreeze-hook’). If using -F with an argument, do not follow -F with a space (for example: ‘-F/var/run/fsfreezehook.sh’).
Specify the directory to store state information (absolute paths only, default is ‘/var/run’).
Log extra debugging information.
Print version information and exit.
Daemonize after startup (detach from terminal).
Comma-separated list of RPCs to disable (no spaces, ‘?’ to list available RPCs).
Dump the configuration in a format compatible with qemu-ga.conf and exit.
Display this help and exit.
The syntax of the qemu-ga.conf configuration file follows the Desktop Entry Specification, here is a quick summary: it consists of groups of key-value pairs, interspersed with comments.
# qemu-ga configuration sample [general] daemonize = 0 pidfile = /var/run/qemu-ga.pid verbose = 0 method = virtio-serial path = /dev/virtio-ports/org.qemu.guest_agent.0 statedir = /var/run
The list of keys follows the command line options:
The following OS are supported in user space emulation:
QEMU user space emulation has the following notable features:
QEMU includes a generic system call translator. This means that the parameters of the system calls can be converted to fix endianness and 32/64-bit mismatches between hosts and targets. IOCTLs can be converted too.
QEMU can redirect to the running program all signals coming from
the host (such as SIGALRM
), as well as synthesize signals from
virtual CPU exceptions (for example SIGFPE
when the program
executes a division by zero).
QEMU relies on the host kernel to emulate most signal system calls, for example to emulate the signal mask. On Linux, QEMU supports both normal and real-time signals.
On Linux, QEMU can emulate the clone
syscall and create a real
host thread (with a separate virtual CPU) for each emulated thread.
Note that not all targets currently emulate atomic operations correctly.
x86 and ARM use a global lock in order to preserve their semantics.
QEMU was conceived so that ultimately it can emulate itself. Although it is not very useful, it is an important test to show the power of the emulator.
In order to launch a Linux process, QEMU needs the process executable itself and all the target (x86) dynamic libraries used by it.
qemu-i386 -L / /bin/ls
-L /
tells that the x86 dynamic linker must be searched with a
/ prefix.
qemu-i386 -L / qemu-i386 -L / /bin/ls
LD_LIBRARY_PATH
is not set:
unset LD_LIBRARY_PATH
Then you can launch the precompiled ls x86 executable:
qemu-i386 tests/i386/ls
You can look at scripts/qemu-binfmt-conf.sh so that
QEMU is automatically launched by the Linux kernel when you try to
launch x86 executables. It requires the binfmt_misc
module in the
Linux kernel.
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \ /usr/local/qemu-i386/bin/ls-i386
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
${HOME}/.wine
directory is saved to ${HOME}/.wine.org
.
qemu-i386 /usr/local/qemu-i386/wine/bin/wine \ /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
qemu-i386
[-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]
Print the help
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
Set the x86 stack size in bytes (default=524288)
Select CPU model (-cpu help for list and additional feature selection)
Set environment var to value.
Remove var from the environment.
Offset guest address by the specified number of bytes. This is useful when the address region required by guest applications is reserved on the host. This option is currently only supported on some hosts.
Pre-allocate a guest virtual address space of the given size (in bytes). "G", "M", and "k" suffixes may be used when specifying the size.
Debug options:
Activate logging of the specified items (use ’-d help’ for a list of log items)
Act as if the host page size was ’pagesize’ bytes
Wait gdb connection to port
Run the emulation in single step mode.
Environment variables:
QEMU_STRACE
Print system calls and arguments similar to the ’strace’ program (NOTE: the actual ’strace’ program will not work because the user space emulator hasn’t implemented ptrace). At the moment this is incomplete. All system calls that don’t have a specific argument format are printed with information for six arguments. Many flag-style arguments don’t have decoders and will show up as numbers.
qemu-alpha
TODO.
qemu-armeb
TODO.
qemu-arm
is also capable of running ARM "Angel" semihosted ELF
binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
configurations), and arm-uclinux bFLT format binaries.
qemu-m68k
is capable of running semihosted binaries using the BDM
(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
coldfire uClinux bFLT format binaries.
The binary format is detected automatically.
qemu-cris
TODO.
qemu-i386
TODO.
qemu-x86_64
TODO.
qemu-microblaze
TODO.
qemu-mips
TODO.
qemu-mipsel
TODO.
qemu-nios2
TODO.
qemu-ppc64abi32
TODO.
qemu-ppc64
TODO.
qemu-ppc
TODO.
qemu-sh4eb
TODO.
qemu-sh4
TODO.
qemu-sparc
can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
qemu-sparc32plus
can execute Sparc32 and SPARC32PLUS binaries
(Sparc64 CPU, 32 bit ABI).
qemu-sparc64
can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
In order to launch a BSD process, QEMU needs the process executable itself and all the target dynamic libraries used by it.
qemu-sparc64 /bin/ls
qemu-sparc64
[-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
Print the help
Set the library root path (default=/)
Set the stack size in bytes (default=524288)
Start with an empty environment. Without this option, the initial environment is a copy of the caller’s environment.
Set environment var to value.
Remove var from the environment.
Set the type of the emulated BSD Operating system. Valid values are FreeBSD, NetBSD and OpenBSD (default).
Debug options:
Activate logging of the specified items (use ’-d help’ for a list of log items)
Act as if the host page size was ’pagesize’ bytes
Run the emulation in single step mode.
 When it first encounters a piece of code, it converts it to the host instruction set. Usually dynamic translators are very complicated and highly CPU dependent. QEMU uses some tricks which make it relatively easily portable and simple while achieving good performances.
QEMU’s dynamic translation backend is called TCG, for "Tiny Code
Generator". For more information, please take a look at tcg/README
.
Some notable features of QEMU’s dynamic translator are:
The target CPUs have many internal states which change the way it evaluates instructions. In order to achieve a good speed, the translation phase considers that some state information of the virtual CPU cannot change in it. The state is recorded in the Translation Block (TB). If the state changes (e.g. privilege level), a new TB will be generated and the previous TB won’t be used anymore until the state matches the state recorded in the previous TB. The same idea can be applied to other aspects of the CPU state. For example, on x86, if the SS, DS and ES segments have a zero base, then the translator does not even generate an addition for the segment base.
After each translated basic block is executed, QEMU uses the simulated Program Counter (PC) and other cpu state information (such as the CS segment base value) to find the next basic block.
In order to accelerate the most common cases where the new simulated PC is known, QEMU can patch a basic block so that it jumps directly to the next one.
The most portable code uses an indirect jump. An indirect jump makes
it easier to make the jump target modification atomic. On some host
architectures (such as x86 or PowerPC), the JUMP
opcode is
directly patched so that the block chaining has no overhead.
Self-modifying code is a special challenge in x86 emulation because no instruction cache invalidation is signaled by the application when code is modified.
User-mode emulation marks a host page as write-protected (if it is not already read-only) every time translated code is generated for a basic block. Then, if a write access is done to the page, Linux raises a SEGV signal. QEMU then invalidates all the translated code in the page and enables write accesses to the page. For system emulation, write protection is achieved through the software MMU.
Correct translated code invalidation is done efficiently by maintaining a linked list of every translated block contained in a given page. Other linked lists are also maintained to undo direct block chaining.
On RISC targets, correctly written software uses memory barriers and cache flushes, so some of the protection above would not be necessary. However, QEMU still requires that the generated code always matches the target instructions in memory in order to handle exceptions correctly.
longjmp() is used when an exception such as division by zero is encountered.
The host SIGSEGV and SIGBUS signal handlers are used to get invalid memory accesses. QEMU keeps a map from host program counter to target program counter, and looks up where the exception happened based on the host program counter at the exception point.
On some targets, some bits of the virtual CPU’s state are not flushed to the memory until the end of the translation block. This is done for internal emulation state that is rarely accessed directly by the program and/or changes very often throughout the execution of a translation block—this includes condition codes on x86, delay slots on SPARC, conditional execution on ARM, and so on. This state is stored for each target instruction, and looked up on exceptions.
For system emulation QEMU uses a software MMU. In that mode, the MMU virtual to physical address translation is done at every memory access.
QEMU uses an address translation cache (TLB) to speed up the translation. In order to avoid flushing the translated code each time the MMU mappings change, all caches in QEMU are physically indexed. This means that each basic block is indexed with its physical address.
In order to avoid invalidating the basic block chain when MMU mappings change, chaining is only performed when the destination of the jump shares a page with the basic block that is performing the jump.
The MMU can also distinguish RAM and ROM memory areas from MMIO memory areas. Access is faster for RAM and ROM because the translation cache also hosts the offset between guest address and host memory. Accessing MMIO memory areas instead calls out to C code for device emulation. Finally, the MMU helps tracking dirty pages and pages pointed to by translation blocks.
Like bochs [1], QEMU emulates an x86 CPU. But QEMU is much faster than bochs as it uses dynamic compilation. Bochs is closely tied to x86 PC emulation while QEMU can emulate several processors.
Like Valgrind [2], QEMU does user space emulation and dynamic translation. Valgrind is mainly a memory debugger while QEMU has no support for it (QEMU could be used to detect out of bound memory accesses as Valgrind, but it has no support to track uninitialised data as Valgrind does). The Valgrind dynamic translator generates better code than QEMU (in particular it does register allocation) but it is closely tied to an x86 host and target and has no support for precise exceptions and system emulation.
EM86 [3] is the closest project to user space QEMU (and QEMU still uses some of its code, in particular the ELF file loader). EM86 was limited to an alpha host and used a proprietary and slow interpreter (the interpreter part of the FX!32 Digital Win32 code translator [4]).
TWIN from Willows Software was a Windows API emulator like Wine. It is less accurate than Wine but includes a protected mode x86 interpreter to launch x86 Windows executables. Such an approach has greater potential because most of the Windows API is executed natively but it is far more difficult to develop because all the data structures and function parameters exchanged between the API and the x86 code must be converted.
User mode Linux [5] was the only solution before QEMU to launch a Linux kernel as a process while not needing any host kernel patches. However, user mode Linux requires heavy kernel patches while QEMU accepts unpatched Linux kernels. The price to pay is that QEMU is slower.
The Plex86 [6] PC virtualizer is done in the same spirit as the now obsolete qemu-fast system emulator. It requires a patched Linux kernel to work (you cannot launch the same kernel on your PC), but the patches are really small. As it is a PC virtualizer (no emulation is done except for some privileged instructions), it has the potential of being faster than QEMU. The downside is that a complicated (and potentially unsafe) host kernel patch is needed.
The commercial PC Virtualizers (VMWare [7], VirtualPC [8]) are faster than QEMU (without virtualization), but they all need specific, proprietary and potentially unsafe host drivers. Moreover, they are unable to provide cycle exact simulation as an emulator can.
VirtualBox [9], Xen [10] and KVM [11] are based on QEMU. QEMU-SystemC [12] uses QEMU to simulate a system where some hardware devices are developed in SystemC.
http://bochs.sourceforge.net/, the Bochs IA-32 Emulator Project, by Kevin Lawton et al.
http://www.valgrind.org/, Valgrind, an open-source memory debugger for GNU/Linux.
http://ftp.dreamtime.org/pub/linux/Linux-Alpha/em86/v0.2/docs/em86.html, the EM86 x86 emulator on Alpha-Linux.
http://www.usenix.org/publications/library/proceedings/usenix-nt97/full_papers/chernoff/chernoff.pdf, DIGITAL FX!32: Running 32-Bit x86 Applications on Alpha NT, by Anton Chernoff and Ray Hookway.
http://user-mode-linux.sourceforge.net/, The User-mode Linux Kernel.
http://www.plex86.org/, The new Plex86 project.
http://www.vmware.com/, The VMWare PC virtualizer.
https://www.microsoft.com/download/details.aspx?id=3702, The VirtualPC PC virtualizer.
http://virtualbox.org/, The VirtualBox PC virtualizer.
http://www.xen.org/, The Xen hypervisor.
http://www.linux-kvm.org/, Kernel Based Virtual Machine (KVM).
http://www.greensocs.com/projects/QEMUSystemC, QEMU-SystemC, a hardware co-simulator.
In general features are intended to be supported indefinitely once introduced into QEMU. In the event that a feature needs to be removed, it will be listed in this appendix. The feature will remain functional for 2 releases prior to actual removal. Deprecated features may also generate warnings on the console when QEMU starts up, or if activated via a monitor command, however, this is not a mandatory requirement.
Prior to the 2.10.0 release there was no official policy on how long features would be deprecated prior to their removal, nor any documented list of which features were deprecated. Thus any features deprecated prior to 2.10.0 will be treated as if they were first deprecated in the 2.10.0 release.
What follows is a list of all features currently marked as deprecated.
The “boot=on|off” option to the “-drive” argument is ignored. Applications should use the “bootindex=N” parameter to set an absolute ordering between devices instead.
The “-tdf” argument is ignored. The behaviour implemented by this argument is now the default when using the KVM PIT, but can be requested explicitly using “-global kvm-pit.lost_tick_policy=slew”.
The “-no-kvm-pit-reinjection” argument is now a synonym for setting “-global kvm-pit.lost_tick_policy=discard”.
The “-no-kvm-irqchip” argument is now a synonym for setting “-machine kernel_irqchip=off”.
The “-no-kvm-pit” argument is ignored. It is no longer possible to disable the KVM PIT directly.
The “-no-kvm” argument is now a synonym for setting “-machine accel=tcg”.
The “default” option to the “-mon” argument is now ignored. When multiple monitors were enabled, it indicated which monitor would receive log messages from the various subsystems. This feature is no longer required as messages are now only sent to the monitor in response to explicitly monitor commands.
The “-vnc tls” argument is now a synonym for setting “-object tls-creds-anon,id=tls0” combined with “-vnc tls-creds=tls0’
The “-vnc x509=/path/to/certs” argument is now a synonym for setting “-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=no” combined with “-vnc tls-creds=tls0’
The “-vnc x509verify=/path/to/certs” argument is now a synonym for setting “-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=yes” combined with “-vnc tls-creds=tls0’
The “-tftp /some/dir” argument is now a synonym for setting the “-netdev user,tftp=/some/dir’ argument. The new syntax allows different settings to be provided per NIC.
The “-bootp /some/file” argument is now a synonym for setting the “-netdev user,bootp=/some/file’ argument. The new syntax allows different settings to be provided per NIC.
The “-redir ARGS” argument is now a synonym for setting the “-netdev user,hostfwd=ARGS” argument instead. The new syntax allows different settings to be provided per NIC.
The “-smb /some/dir” argument is now a synonym for setting the “-netdev user,smb=/some/dir” argument instead. The new syntax allows different settings to be provided per NIC.
The “–net channel,ARGS” argument is now a synonym for setting the “-netdev user,guestfwd=ARGS” argument instead.
The “-net vlan=NN” argument is partially replaced with the new “-netdev” argument. The remaining use cases will no longer be directly supported in QEMU.
The “-drive if=scsi” argument is replaced by the the “-device BUS-TYPE” argument combined with “-drive if=none”.
The “–net dump” argument is now replaced with the “-object filter-dump” argument which works in combination with the modern “-netdev“ backends instead.
The “-hdachs” argument is now a synonym for setting the “cyls”, “heads”, “secs”, and “trans” properties on the “ide-hd” device using the “-device” argument. The new syntax allows different settings to be provided per disk.
The “-usbdevice DEV” argument is now a synonym for setting the “-device usb-DEV” argument instead. The deprecated syntax would automatically enable USB support on the machine type. If using the new syntax, USB support must be explicitly enabled via the “-machine usb=on” argument.
The “convert -s snapshot_id_or_name” argument is obsoleted by the “convert -l snapshot_param” argument instead.
The “host_net_add” command is replaced by the “netdev_add” command.
The “host_net_remove” command is replaced by the “netdev_del” command.
The “usb_add” command is replaced by the “device_add” command.
The “usb_del” command is replaced by the “device_del” command.
The “ivshmem” device type is replaced by either the “ivshmem-plain” or “ivshmem-doorbell“ device types.
The “spapr-pci-vfio-host-bridge” device type is replaced by the “spapr-pci-host-bridge” device type.
QEMU is a trademark of Fabrice Bellard.
QEMU is released under the GNU General Public License, version 2. Parts of QEMU have specific licenses, see file LICENSE.
This is the main index. Should we combine all keywords in one index? TODO
| Jump to: | O Q S U |
|---|
| Jump to: | O Q S U |
|---|
This index could be used for command line options and monitor functions.
| Jump to: | -
A B C D E G H I J K L M N O P Q R S T U V W X |
|---|
| Jump to: | -
A B C D E G H I J K L M N O P Q R S T U V W X |
|---|
This is a list of all keystrokes which have a special function in system emulation.
| Jump to: | C |
|---|
| Jump to: | C |
|---|
This index could be used for qdev device names and options.


{% comment %} This snippet is used for user activities or activity feed. Params: activities_page: the page django.core.paginator.Page of activities activity_url: the url for the object's activities obj: the obj the activities are for. activity_source: the source of the activities (optional). Default is to show all. Can be 'USER' or 'SYSTEM'. activity_action: the action of the activity (optional). Defaults to show all actions. Can be one of an action values ("CREATED", "COMMENTED", "UPDATED", "DELETED", etc.) show_activity_comment_form: (optional) boolean indicating if the comment form should be shown at the top of the activities. Default is True. show_activity_type_tabs: (optional) show the activity type tabs at the top of the activities so they can be sorted by type. Default is True. activities_css_class: (optional) an extra css class string to add to the activities container. is_infinite_scroll: (optional) boolean indicating if the activities should use infinite scroll. user_cache: (optional) a dict of users keyed by their user id. This can be useful to prevent user queries on activity "about" objects where select_related and prefetch_related can't be used on the "about" fields since it's a generic foreign key field. {% endcomment %} {% load humanize activity_tags %} {% spaceless %} {% with activities_object_list=activities_page.object_list %}
{% with action=activity_action.lower source=activity_source.lower %}- All
- Comments
- Activity
{% endwith %}
{% endif %} {% endif %}{% for activity in activities_object_list %} {% if obj == activity.about %} {% render_activity activity=activity activity_url=activity_url user_cache=user_cache %} {% else %} {% render_activity activity=activity show_reference_obj=True activity_url=activity_url user_cache=user_cache %} {% endif %} {% empty %}- No activities found.
{% endfor %}
{% if activities_page.has_next %}