\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename qemu-doc.info
+@include version.texi
@documentlanguage en
@documentencoding UTF-8
-@settitle QEMU Emulator User Documentation
+@settitle QEMU version @value{VERSION} User Documentation
@exampleindent 0
@paragraphindent 0
@c %**end of header
@iftex
@titlepage
@sp 7
-@center @titlefont{QEMU Emulator}
+@center @titlefont{QEMU version @value{VERSION}}
@sp 1
@center @titlefont{User Documentation}
@sp 3
@menu
* Introduction::
-* Installation::
* QEMU PC System emulator::
* QEMU System emulator for non PC targets::
+* QEMU Guest Agent::
* QEMU User space emulator::
-* compilation:: Compilation from the sources
+* Implementation notes::
+* Deprecated features::
* License::
* Index::
@end menu
QEMU is a FAST! processor emulator using dynamic translation to
achieve good emulation speed.
+@cindex operating modes
QEMU has two operating modes:
@itemize
-@cindex operating modes
-
-@item
@cindex system emulation
-Full system emulation. In this mode, QEMU emulates a full system (for
+@item Full system emulation. In this mode, QEMU emulates a full system (for
example a PC), including one or several processors and various
peripherals. It can be used to launch different Operating Systems
without rebooting the PC or to debug system code.
-@item
@cindex user mode emulation
-User mode emulation. In this mode, QEMU can launch
+@item User mode emulation. In this mode, QEMU can launch
processes compiled for one CPU on another CPU. It can be used to
launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
to ease cross-compilation and cross-debugging.
@end itemize
-QEMU can run without a host kernel driver and yet gives acceptable
-performance.
+QEMU has the following features:
-For system emulation, the following hardware targets are supported:
@itemize
-@cindex emulated target systems
-@cindex supported target systems
-@item PC (x86 or x86_64 processor)
-@item ISA PC (old style PC without PCI bus)
-@item PREP (PowerPC processor)
-@item G3 Beige PowerMac (PowerPC processor)
-@item Mac99 PowerMac (PowerPC processor, in progress)
-@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
-@item Sun4u/Sun4v (64-bit Sparc processor, in progress)
-@item Malta board (32-bit and 64-bit MIPS processors)
-@item MIPS Magnum (64-bit MIPS processor)
-@item ARM Integrator/CP (ARM)
-@item ARM Versatile baseboard (ARM)
-@item ARM RealView Emulation/Platform baseboard (ARM)
-@item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
-@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
-@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
-@item Freescale MCF5208EVB (ColdFire V2).
-@item Arnewsh MCF5206 evaluation board (ColdFire V2).
-@item Palm Tungsten|E PDA (OMAP310 processor)
-@item N800 and N810 tablets (OMAP2420 processor)
-@item MusicPal (MV88W8618 ARM processor)
-@item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
-@item Siemens SX1 smartphone (OMAP310 processor)
-@item AXIS-Devboard88 (CRISv32 ETRAX-FS).
-@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
-@item Avnet LX60/LX110/LX200 boards (Xtensa)
-@end itemize
+@item QEMU can run without a host kernel driver and yet gives acceptable
+performance. It uses dynamic translation to native code for reasonable speed,
+with support for self-modifying code and precise exceptions.
-@cindex supported user mode targets
-For user emulation, x86 (32 and 64 bit), PowerPC (32 and 64 bit),
-ARM, MIPS (32 bit only), Sparc (32 and 64 bit),
-Alpha, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
+@item It is portable to several operating systems (GNU/Linux, *BSD, Mac OS X,
+Windows) and architectures.
-@node Installation
-@chapter Installation
+@item It performs accurate software emulation of the FPU.
+@end itemize
-If you want to compile QEMU yourself, see @ref{compilation}.
+QEMU user mode emulation has the following features:
+@itemize
+@item Generic Linux system call converter, including most ioctls.
-@menu
-* install_linux:: Linux
-* install_windows:: Windows
-* install_mac:: Macintosh
-@end menu
+@item clone() emulation using native CPU clone() to use Linux scheduler for threads.
-@node install_linux
-@section Linux
-@cindex installation (Linux)
+@item Accurate signal handling by remapping host signals to target signals.
+@end itemize
-If a precompiled package is available for your distribution - you just
-have to install it. Otherwise, see @ref{compilation}.
+QEMU full system emulation has the following features:
+@itemize
+@item
+QEMU uses a full software MMU for maximum portability.
+
+@item
+QEMU can optionally use an in-kernel accelerator, like kvm. The accelerators
+execute most of the guest code natively, while
+continuing to emulate the rest of the machine.
-@node install_windows
-@section Windows
-@cindex installation (Windows)
+@item
+Various hardware devices can be emulated and in some cases, host
+devices (e.g. serial and parallel ports, USB, drives) can be used
+transparently by the guest Operating System. Host device passthrough
+can be used for talking to external physical peripherals (e.g. a
+webcam, modem or tape drive).
-Download the experimental binary installer at
-@url{http://www.free.oszoo.org/@/download.html}.
-TODO (no longer available)
+@item
+Symmetric multiprocessing (SMP) support. Currently, an in-kernel
+accelerator is required to use more than one host CPU for emulation.
-@node install_mac
-@section Mac OS X
+@end itemize
-Download the experimental binary installer at
-@url{http://www.free.oszoo.org/@/download.html}.
-TODO (no longer available)
@node QEMU PC System emulator
@chapter QEMU PC System emulator
@item
CS4231A compatible sound card
@item
-PCI UHCI USB controller and a virtual USB hub.
+PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
@end itemize
SMP is supported with up to 255 CPUs.
@node disk_images
@section Disk Images
-Since version 0.6.1, QEMU supports many disk image formats, including
-growable disk images (their size increase as non empty sectors are
-written), compressed and encrypted disk images. Version 0.8.3 added
-the new qcow2 disk image format which is essential to support VM
-snapshots.
+QEMU supports many disk image formats, including growable disk images
+(their size increase as non empty sectors are written), compressed and
+encrypted disk images.
@menu
* disk_images_quickstart:: Quick start for disk image creation
* vm_snapshots:: VM snapshots
* qemu_img_invocation:: qemu-img Invocation
* qemu_nbd_invocation:: qemu-nbd Invocation
-* qemu_ga_invocation:: qemu-ga Invocation
* disk_images_formats:: Disk image file formats
* host_drives:: Using host drives
* disk_images_fat_images:: Virtual FAT disk images
@include qemu-nbd.texi
-@node qemu_ga_invocation
-@subsection @code{qemu-ga} Invocation
-
-@include qemu-ga.texi
-
@node disk_images_formats
@subsection Disk image file formats
@item backing_fmt
Image format of the base image
@item encryption
-If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC.
+This option is deprecated and equivalent to @code{encrypt.format=aes}
+
+@item encrypt.format
-The use of encryption in qcow and qcow2 images is considered to be flawed by
-modern cryptography standards, suffering from a number of design problems:
+If this is set to @code{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 @code{encrypt.key-secret}
+parameter. LUKS encryption parameters can be tuned with the other
+@code{encrypt.*} parameters.
+
+If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.
+The encryption key is given by the @code{encrypt.key-secret} parameter.
+This encryption format is considered to be flawed by modern cryptography
+standards, suffering from a number of design problems:
@itemize @minus
@item The AES-CBC cipher is used with predictable initialization vectors based
though even this is ineffective with many modern storage technologies.
@end itemize
-Use of qcow / qcow2 encryption with QEMU is deprecated, and support for
-it will go away in a future release. Users are recommended to use an
-alternative encryption technology such as the Linux dm-crypt / LUKS
-system.
+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 @code{luks} format
+should be used instead.
+
+@item encrypt.key-secret
+
+Provides the ID of a @code{secret} object that contains the passphrase
+(@code{encrypt.format=luks}) or encryption key (@code{encrypt.format=aes}).
+
+@item encrypt.cipher-alg
+
+Name of the cipher algorithm and key length. Currently defaults
+to @code{aes-256}. Only used when @code{encrypt.format=luks}.
+
+@item encrypt.cipher-mode
+
+Name of the encryption mode to use. Currently defaults to @code{xts}.
+Only used when @code{encrypt.format=luks}.
+
+@item encrypt.ivgen-alg
+
+Name of the initialization vector generator algorithm. Currently defaults
+to @code{plain64}. Only used when @code{encrypt.format=luks}.
+
+@item encrypt.ivgen-hash-alg
+
+Name of the hash algorithm to use with the initialization vector generator
+(if required). Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
+
+@item encrypt.hash-alg
+
+Name of the hash algorithm to use for PBKDF algorithm
+Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
+
+@item encrypt.iter-time
+
+Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
+Defaults to @code{2000}. Only used when @code{encrypt.format=luks}.
@item cluster_size
Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
@item backing_file
File name of a base image (see @option{create} subcommand)
@item encryption
-If this option is set to @code{on}, the image is encrypted.
+This option is deprecated and equivalent to @code{encrypt.format=aes}
+
+@item encrypt.format
+If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.
+The encryption key is given by the @code{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 @code{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 @code{qcow2} format
+instead with @code{encrypt.format=luks}.
+
+@item encrypt.key-secret
+
+Provides the ID of a @code{secret} object that contains the encryption
+key (@code{encrypt.format=aes}).
+
+@end table
+
+@item luks
+
+LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
+
+Supported options:
+@table @code
+
+@item key-secret
+
+Provides the ID of a @code{secret} object that contains the passphrase.
+
+@item cipher-alg
+
+Name of the cipher algorithm and key length. Currently defaults
+to @code{aes-256}.
+
+@item cipher-mode
+
+Name of the encryption mode to use. Currently defaults to @code{xts}.
+
+@item ivgen-alg
+
+Name of the initialization vector generator algorithm. Currently defaults
+to @code{plain64}.
+
+@item ivgen-hash-alg
+
+Name of the hash algorithm to use with the initialization vector generator
+(if required). Defaults to @code{sha256}.
+
+@item hash-alg
+
+Name of the hash algorithm to use for PBKDF algorithm
+Defaults to @code{sha256}.
+
+@item iter-time
+
+Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
+Defaults to @code{2000}.
+
@end table
@item vdi
File name of a base image (see @option{create} subcommand).
@item compat6
Create a VMDK version 6 image (instead of version 4)
+@item hwversion
+Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
+if hwversion is specified.
@item subformat
Specifies which VMDK subformat to use. Valid options are
@code{monolithicSparse} (default),
command line.
If the initiator-name is not specified qemu will use a default name
-of 'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
+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.
-
@example
Setting a specific initiator name to use when logging in to the target
-iscsi initiator-name=iqn.qemu.test:my-initiator
@node disk_images_gluster
@subsection GlusterFS disk images
-GlusterFS is an user space distributed file system.
+GlusterFS is a user space distributed file system.
You can boot from the GlusterFS disk image with the command:
@example
-qemu-system-x86_64 -drive file=gluster[+@var{transport}]://[@var{server}[:@var{port}]]/@var{volname}/@var{image}[?socket=...]
+URI:
+qemu-system-x86_64 -drive file=gluster[+@var{type}]://[@var{host}[:@var{port}]]/@var{volume}/@var{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":"..."@}]@}@}'
@end example
@var{gluster} is the protocol.
-@var{transport} specifies the transport type used to connect to gluster
+@var{type} specifies the transport type used to connect to gluster
management daemon (glusterd). Valid transport types are
-tcp, unix and rdma. If a transport type isn't specified, then tcp
-type is assumed.
+tcp and unix. In the URI form, if a transport type isn't specified,
+then tcp type is assumed.
-@var{server} specifies the server where the volume file specification for
-the given volume resides. This can be either hostname, ipv4 address
-or ipv6 address. ipv6 address needs to be within square brackets [ ].
-If transport type is unix, then @var{server} field should not be specified.
+@var{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 @var{host} field should not be specified.
Instead @var{socket} field needs to be populated with the path to unix domain
socket.
@var{port} is the port number on which glusterd is listening. This is optional
-and if not specified, QEMU will send 0 which will make gluster to use the
-default port. If the transport type is unix, then @var{port} should not be
-specified.
+and if not specified, it defaults to port 24007. If the transport type is unix,
+then @var{port} should not be specified.
+
+@var{volume} is the name of the gluster volume which contains the disk image.
+
+@var{path} is the path to the actual disk image that resides on gluster volume.
+
+@var{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
+
+@var{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.
+
-@var{volname} is the name of the gluster volume which contains the disk image.
-@var{image} is the path to the actual disk image that resides on gluster volume.
You can create a GlusterFS disk image with the command:
@example
-qemu-img create gluster://@var{server}/@var{volname}/@var{image} @var{size}
+qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size}
@end example
Examples
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://1.2.3.4:24007/testvol/a.img
+qemu-system-x86_64 -drive file=gluster://1.2.3.4/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":"1.2.3.4","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=1.2.3.4,file.server.0.port=24007,
+ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
@end example
@node disk_images_ssh
@node pcsys_usb
@section USB emulation
-QEMU emulates a PCI UHCI USB controller. You can virtually plug
-virtual USB devices or real host USB devices (experimental, works only
-on Linux hosts). QEMU will automatically create and connect virtual USB hubs
-as necessary to connect multiple USB devices.
+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.
@menu
* usb_devices::
@node usb_devices
@subsection Connecting USB devices
-USB devices can be connected with the @option{-usbdevice} commandline option
-or the @code{usb_add} monitor command. Available devices are:
+USB devices can be connected with the @option{-device usb-...} command line
+option or the @code{device_add} monitor command. Available devices are:
@table @code
-@item mouse
+@item usb-mouse
Virtual Mouse. This will override the PS/2 mouse emulation when activated.
-@item tablet
+@item 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.
-@item disk:@var{file}
-Mass storage device based on @var{file} (@pxref{disk_images})
-@item host:@var{bus.addr}
-Pass through the host device identified by @var{bus.addr}
-(Linux only)
-@item host:@var{vendor_id:product_id}
-Pass through the host device identified by @var{vendor_id:product_id}
-(Linux only)
-@item wacom-tablet
+@item usb-storage,drive=@var{drive_id}
+Mass storage device backed by @var{drive_id} (@pxref{disk_images})
+@item usb-uas
+USB attached SCSI device, see
+@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
+for details
+@item usb-bot
+Bulk-only transport storage device, see
+@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
+for details here, too
+@item usb-mtp,x-root=@var{dir}
+Media transfer protocol device, using @var{dir} as root of the file tree
+that is presented to the guest.
+@item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
+Pass through the host device identified by @var{bus} and @var{addr}
+@item usb-host,vendorid=@var{vendor},productid=@var{product}
+Pass through the host device identified by @var{vendor} and @var{product} ID
+@item usb-wacom-tablet
Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
above but it can be used with the tslib library because in addition to touch
coordinates it reports touch pressure.
-@item keyboard
+@item usb-kbd
Standard USB keyboard. Will override the PS/2 keyboard (if present).
-@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
+@item usb-serial,chardev=@var{id}
Serial converter. This emulates an FTDI FT232BM chip connected to host character
-device @var{dev}. The available character devices are the same as for the
-@code{-serial} option. The @code{vendorid} and @code{productid} options can be
-used to override the default 0403:6001. For instance,
-@example
-usb_add serial:productid=FA00:tcp:192.168.0.2:4444
-@end example
-will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
-serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
-@item braille
+device @var{id}.
+@item usb-braille,chardev=@var{id}
Braille device. This will use BrlAPI to display the braille output on a real
-or fake device.
-@item net:@var{options}
-Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
-specifies NIC options as with @code{-net nic,}@var{options} (see description).
+or fake device referenced by @var{id}.
+@item usb-net[,netdev=@var{id}]
+Network adapter that supports CDC ethernet and RNDIS protocols. @var{id}
+specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}.
For instance, user-mode networking can be used with
@example
-qemu-system-i386 [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
-@end example
-Currently this cannot be used in machines that support PCI NICs.
-@item bt[:@var{hci-type}]
-Bluetooth dongle whose type is specified in the same format as with
+qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
+@end example
+@item usb-ccid
+Smartcard reader device
+@item usb-audio
+USB audio device
+@item usb-bt-dongle
+Bluetooth dongle for the transport layer of HCI. It is connected to HCI
+scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
+Note that the syntax for the @code{-device usb-bt-dongle} option is not as
+useful yet as it was with the legacy @code{-usbdevice} option. So to
+configure an USB bluetooth device, you might need to use
+"@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
+bluetooth dongle whose type is specified in the same format as with
the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
This USB device implements the USB Transport Layer of HCI. Example
@item Add the device in QEMU by using:
@example
-usb_add host:1234:5678
+device_add usb-host,vendorid=0x1234,productid=0x5678
@end example
-Normally the guest OS should report that a new USB device is
-plugged. You can use the option @option{-usbdevice} to do the same.
+Normally the guest OS should report that a new USB device is plugged.
+You can use the option @option{-device usb-host,...} to do the same.
@item Now you can try to use the host USB device in QEMU.
unprivileged user, an environment variable SASL_CONF_PATH can be used
to make it search alternate locations for the service config.
-The default configuration might contain
+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
@example
-mech_list: digest-md5
-sasldb_path: /etc/qemu/passwd.db
+mech_list: gssapi
+keytab: /etc/qemu/krb5.tab
@end example
-This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
-Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
-in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
-command. While this mechanism is easy to configure and use, it is not
-considered secure by modern standards, so only suitable for developers /
-ad-hoc testing.
+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 'qemu/somehost.example.com@@EXAMPLE.COM' replacing
+'somehost.example.com' with the fully qualified host name of the machine
+running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
-A more serious deployment might use Kerberos, which is done with the 'gssapi'
-mechanism
+When using TLS, if username+password authentication is desired, then a
+reasonable configuration is
@example
-mech_list: gssapi
-keytab: /etc/qemu/krb5.tab
+mech_list: scram-sha-1
+sasldb_path: /etc/qemu/passwd.db
@end example
-For this to work the administrator of your KDC must generate a Kerberos
-principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM'
-replacing 'somehost.example.com' with the fully qualified host name of the
-machine running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
+The saslpasswd2 program can be used to populate the passwd.db file with
+accounts.
-Other configurations will be left as an exercise for the reader. It should
-be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
-encryption. For all other mechanisms, VNC should always be configured to
-use TLS and x509 certificates to protect security credentials from snooping.
+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.
@node gdb_usage
@section GDB usage
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
-@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
-problem. Note that no such tool is needed for NT, 2000 or XP.
+@url{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.
@subsubsection Windows 2000 disk full problem
@subsubsection CPU usage reduction
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 @url{http://www.vmware.com/software/dosidle210.zip} to solve this
-problem.
+it takes host CPU cycles even when idle. You can install the utility from
+@url{http://web.archive.org/web/20051222085335/http://www.vmware.com/software/dosidle210.zip}
+to solve this problem.
@node QEMU System emulator for non PC targets
@chapter QEMU System emulator for non PC targets
(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 and Niagara emulators are still a work in progress.
+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 @url{http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2}
+and is able to boot the disk.s10hw2 Solaris image.
+@example
+qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
+ -nographic -m 256 \
+ -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
+@end example
+
QEMU emulates the following peripherals:
qemu-system-sparc64 -prom-env 'auto-boot?=false'
@end example
-@item -M [sun4u|sun4v|Niagara]
+@item -M [sun4u|sun4v|niagara]
Set the emulated machine type. The default is sun4u.
@end table
+@c man end
+
@node ColdFire System emulator
@section ColdFire System emulator
@cindex system emulation (ColdFire)
@end table
+@c man end
+
@node Cris System emulator
@section Cris System emulator
@cindex system emulation (Cris)
so should only be used with trusted guest OS.
@end table
+
+@c man end
+
+@node QEMU Guest Agent
+@chapter QEMU Guest Agent invocation
+
+@include qemu-ga.texi
+
@node QEMU User space emulator
@chapter QEMU User space emulator
@menu
* Supported Operating Systems ::
+* Features::
* Linux User space emulator::
* BSD User space emulator ::
@end menu
BSD (referred as qemu-bsd-user)
@end itemize
+@node Features
+@section Features
+
+QEMU user space emulation has the following notable features:
+
+@table @strong
+@item System call translation:
+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.
+
+@item POSIX signal handling:
+QEMU can redirect to the running program all signals coming from
+the host (such as @code{SIGALRM}), as well as synthesize signals from
+virtual CPU exceptions (for example @code{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.
+
+@item Threading:
+On Linux, QEMU can emulate the @code{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.
+@end table
+
+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.
+
@node Linux User space emulator
@section Linux User space emulator
@command{qemu-mips} TODO.
@command{qemu-mipsel} TODO.
+@cindex user mode (NiosII)
+@command{qemu-nios2} TODO.
+
@cindex user mode (PowerPC)
@command{qemu-ppc64abi32} TODO.
@command{qemu-ppc64} TODO.
Run the emulation in single step mode.
@end table
-@node compilation
-@chapter Compilation from the sources
-@menu
-* Linux/Unix::
-* Windows::
-* Cross compilation for Windows with Linux::
-* Mac OS X::
-* Make targets::
-@end menu
+@include qemu-tech.texi
-@node Linux/Unix
-@section Linux/Unix
+@node Deprecated features
+@appendix Deprecated features
-@subsection Compilation
+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.
-First you must decompress the sources:
-@example
-cd /tmp
-tar zxvf qemu-x.y.z.tar.gz
-cd qemu-x.y.z
-@end example
+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.
-Then you configure QEMU and build it (usually no options are needed):
-@example
-./configure
-make
-@end example
+What follows is a list of all features currently marked as
+deprecated.
-Then type as root user:
-@example
-make install
-@end example
-to install QEMU in @file{/usr/local}.
+@section System emulator command line arguments
-@node Windows
-@section Windows
+@subsection -drive boot=on|off (since 1.3.0)
-@itemize
-@item Install the current versions of MSYS and MinGW from
-@url{http://www.mingw.org/}. You can find detailed installation
-instructions in the download section and the FAQ.
+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.
-@item Download
-the MinGW development library of SDL 1.2.x
-(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
-@url{http://www.libsdl.org}. Unpack it in a temporary place and
-edit the @file{sdl-config} script so that it gives the
-correct SDL directory when invoked.
+@subsection -tdf (since 1.3.0)
-@item Install the MinGW version of zlib and make sure
-@file{zlib.h} and @file{libz.dll.a} are in
-MinGW's default header and linker search paths.
+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''.
-@item Extract the current version of QEMU.
+@subsection -no-kvm-pit-reinjection (since 1.3.0)
-@item Start the MSYS shell (file @file{msys.bat}).
+The ``-no-kvm-pit-reinjection'' argument is now a
+synonym for setting ``-global kvm-pit.lost_tick_policy=discard''.
-@item Change to the QEMU directory. Launch @file{./configure} and
-@file{make}. If you have problems using SDL, verify that
-@file{sdl-config} can be launched from the MSYS command line.
+@subsection -no-kvm-irqchip (since 1.3.0)
-@item You can install QEMU in @file{Program Files/QEMU} by typing
-@file{make install}. Don't forget to copy @file{SDL.dll} in
-@file{Program Files/QEMU}.
+The ``-no-kvm-irqchip'' argument is now a synonym for
+setting ``-machine kernel_irqchip=off''.
-@end itemize
+@subsection -no-kvm-pit (since 1.3.0)
-@node Cross compilation for Windows with Linux
-@section Cross compilation for Windows with Linux
+The ``-no-kvm-pit'' argument is ignored. It is no longer
+possible to disable the KVM PIT directly.
-@itemize
-@item
-Install the MinGW cross compilation tools available at
-@url{http://www.mingw.org/}.
+@subsection -no-kvm (since 1.3.0)
-@item Download
-the MinGW development library of SDL 1.2.x
-(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
-@url{http://www.libsdl.org}. Unpack it in a temporary place and
-edit the @file{sdl-config} script so that it gives the
-correct SDL directory when invoked. Set up the @code{PATH} environment
-variable so that @file{sdl-config} can be launched by
-the QEMU configuration script.
+The ``-no-kvm'' argument is now a synonym for setting
+``-machine accel=tcg''.
-@item Install the MinGW version of zlib and make sure
-@file{zlib.h} and @file{libz.dll.a} are in
-MinGW's default header and linker search paths.
+@subsection -mon default=on (since 2.4.0)
-@item
-Configure QEMU for Windows cross compilation:
-@example
-PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
-@end example
-The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
-MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
-We set the @code{PATH} environment variable to ensure the MinGW version of @file{sdl-config} is used and
-use --cross-prefix to specify the name of the cross compiler.
-You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/QEMU}.
+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.
-Under Fedora Linux, you can run:
-@example
-yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
-@end example
-to get a suitable cross compilation environment.
+@subsection -vnc tls (since 2.5.0)
-@item You can install QEMU in the installation directory by typing
-@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
-installation directory.
+The ``-vnc tls'' argument is now a synonym for setting
+``-object tls-creds-anon,id=tls0'' combined with
+``-vnc tls-creds=tls0'
-@end itemize
+@subsection -vnc x509 (since 2.5.0)
-Wine can be used to launch the resulting qemu-system-i386.exe
-and all other qemu-system-@var{target}.exe compiled for Win32.
+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'
-@node Mac OS X
-@section Mac OS X
+@subsection -vnc x509verify (since 2.5.0)
-System Requirements:
-@itemize
-@item Mac OS 10.5 or higher
-@item The clang compiler shipped with Xcode 4.2 or higher,
-or GCC 4.3 or higher
-@end itemize
+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'
-Additional Requirements (install in order):
-@enumerate
-@item libffi: @uref{https://sourceware.org/libffi/}
-@item gettext: @uref{http://www.gnu.org/software/gettext/}
-@item glib: @uref{http://ftp.gnome.org/pub/GNOME/sources/glib/}
-@item pkg-config: @uref{http://www.freedesktop.org/wiki/Software/pkg-config/}
-@item autoconf: @uref{http://www.gnu.org/software/autoconf/autoconf.html}
-@item automake: @uref{http://www.gnu.org/software/automake/}
-@item pixman: @uref{http://www.pixman.org/}
-@end enumerate
+@subsection -tftp (since 2.6.0)
-* You may find it easiest to get these from a third-party packager
-such as Homebrew, Macports, or Fink.
+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.
-After downloading the QEMU source code, double-click it to expand it.
+@subsection -bootp (since 2.6.0)
-Then configure and make QEMU:
-@example
-./configure
-make
-@end example
+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.
-If you have a recent version of Mac OS X (OSX 10.7 or better
-with Xcode 4.2 or better) we recommend building QEMU with the
-default compiler provided by Apple, for your version of Mac OS X
-(which will be 'clang'). The configure script will
-automatically pick this.
+@subsection -redir (since 2.6.0)
-Note: If after the configure step you see a message like this:
-@example
-ERROR: Your compiler does not support the __thread specifier for
- Thread-Local Storage (TLS). Please upgrade to a version that does.
-@end example
-you may have to build your own version of gcc from source. Expect that to take
-several hours. More information can be found here:
-@uref{https://gcc.gnu.org/install/} @*
+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.
-These are some of the third party binaries of gcc available for download:
-@itemize
-@item Homebrew: @uref{http://brew.sh/}
-@item @uref{https://www.litebeam.net/gcc/gcc_472.pkg}
-@item @uref{http://www.macports.org/ports.php?by=name&substr=gcc}
-@end itemize
+@subsection -smb (since 2.6.0)
-You can have several versions of GCC on your system. To specify a certain version,
-use the --cc and --cxx options.
-@example
-./configure --cxx=<path of your c++ compiler> --cc=<path of your c compiler> <other options>
-@end example
+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.
-@node Make targets
-@section Make targets
+@subsection -net channel (since 2.6.0)
-@table @code
+The ``--net channel,ARGS'' argument is now a synonym for setting
+the ``-netdev user,guestfwd=ARGS'' argument instead.
-@item make
-@item make all
-Make everything which is typically needed.
+@subsection -net vlan (since 2.9.0)
-@item install
-TODO
+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.
-@item install-doc
-TODO
+@subsection -drive if=scsi (since 2.9.0)
-@item make clean
-Remove most files which were built during make.
+The ``-drive if=scsi'' argument is replaced by the the
+``-device BUS-TYPE'' argument combined with ``-drive if=none''.
-@item make distclean
-Remove everything which was built during make.
+@subsection -net dump (since 2.10.0)
-@item make dvi
-@item make html
-@item make info
-@item make pdf
-Create documentation in dvi, html, info or pdf format.
+The ``--net dump'' argument is now replaced with the
+``-object filter-dump'' argument which works in combination
+with the modern ``-netdev`` backends instead.
-@item make cscope
-TODO
+@subsection -hdachs (since 2.10.0)
-@item make defconfig
-(Re-)create some build configuration files.
-User made changes will be overwritten.
+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.
-@item tar
-@item tarbin
-TODO
+@subsection -usbdevice (since 2.10.0)
-@end table
+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.
+
+@section qemu-img command line arguments
+
+@subsection convert -s (since 2.0.0)
+
+The ``convert -s snapshot_id_or_name'' argument is obsoleted
+by the ``convert -l snapshot_param'' argument instead.
+
+@section System emulator human monitor commands
+
+@subsection host_net_add (since 2.10.0)
+
+The ``host_net_add'' command is replaced by the ``netdev_add'' command.
+
+@subsection host_net_remove (since 2.10.0)
+
+The ``host_net_remove'' command is replaced by the ``netdev_del'' command.
+
+@subsection usb_add (since 2.10.0)
+
+The ``usb_add'' command is replaced by the ``device_add'' command.
+
+@subsection usb_del (since 2.10.0)
+
+The ``usb_del'' command is replaced by the ``device_del'' command.
+
+@section System emulator devices
+
+@subsection ivshmem (since 2.6.0)
+
+The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
+or ``ivshmem-doorbell`` device types.
+
+@subsection spapr-pci-vfio-host-bridge (since 2.6.0)
+
+The ``spapr-pci-vfio-host-bridge'' device type is replaced by
+the ``spapr-pci-host-bridge'' device type.
@node License
@appendix License
QEMU is a trademark of Fabrice Bellard.
-QEMU is released under the GNU General Public License (TODO: add link).
-Parts of QEMU have specific licenses, see file LICENSE.
-
-TODO (refer to file LICENSE, include it, include the GPL?)
+QEMU is released under the
+@url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
+version 2. Parts of QEMU have specific licenses, see file
+@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
@node Index
@appendix Index
projects / mirror_qemu.git / blobdiff