X-Git-Url: https://repo.jachan.dev/qemu.git/blobdiff_plain/736a83fae4e00215537e91bffdde994ad08ec049..ee29bdb6a7878205d41a46aa30f17bb831910b85:/qemu-doc.texi diff --git a/qemu-doc.texi b/qemu-doc.texi index 3840585e63..d2986cba50 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -1,11 +1,12 @@ \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 @@ -19,7 +20,7 @@ @iftex @titlepage @sp 7 -@center @titlefont{QEMU Emulator} +@center @titlefont{QEMU version @value{VERSION}} @sp 1 @center @titlefont{User Documentation} @sp 3 @@ -34,6 +35,7 @@ * Introduction:: * QEMU PC System emulator:: * QEMU System emulator for non PC targets:: +* QEMU Guest Agent:: * QEMU User space emulator:: * Implementation notes:: * License:: @@ -182,7 +184,7 @@ Gravis Ultrasound GF1 sound card @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. @@ -384,11 +386,9 @@ CPU registers by prefixing them with @emph{$}. @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 @@ -396,7 +396,6 @@ snapshots. * 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 @@ -490,11 +489,6 @@ state is not saved or restored properly (in particular USB). @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 @@ -1357,10 +1351,10 @@ monitor (@pxref{pcsys_keys}). @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:: @@ -1369,53 +1363,64 @@ as necessary to connect multiple 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 @@ -1460,11 +1465,11 @@ hubs, it won't work). @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. @@ -1732,37 +1737,45 @@ 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. -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 @@ -1878,8 +1891,8 @@ resolution modes which the Cirrus Logic BIOS does not support (i.e. >= 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 @@ -1927,9 +1940,9 @@ vvfat block device ("-hdb fat:directory_which_holds_the_SP"). @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 @@ -2551,6 +2564,8 @@ so should only be used with trusted guest OS. @end table +@c man end + @node ColdFire System emulator @section ColdFire System emulator @cindex system emulation (ColdFire) @@ -2595,6 +2610,8 @@ so should only be used with trusted guest OS. @end table +@c man end + @node Cris System emulator @section Cris System emulator @cindex system emulation (Cris) @@ -2666,6 +2683,14 @@ Note that this allows guest direct access to the host filesystem, 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 @@ -2901,6 +2926,9 @@ The binary format is detected automatically. @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. @@ -2998,10 +3026,10 @@ Run the emulation in single step mode. 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