X-Git-Url: https://repo.jachan.dev/qemu.git/blobdiff_plain/b0083267444a5e0f28391f6c2831a539f878d424..8f3cd250a897213d39e621e3d824507b48158d42:/qemu-doc.texi diff --git a/qemu-doc.texi b/qemu-doc.texi index 282bc3dc35..f7ad1dfe4b 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -135,6 +135,7 @@ accelerator is required to use more than one host CPU for emulation. * pcsys_keys:: Keys in the graphical frontends * mux_keys:: Keys in the character backend multiplexer * pcsys_monitor:: QEMU Monitor +* cpu_models:: CPU models * disk_images:: Disk Images * pcsys_network:: Network emulation * pcsys_other_devs:: Other Devices @@ -602,6 +603,11 @@ The monitor understands integers expressions for every integer argument. You can use register names to get the value of specifics CPU registers by prefixing them with @emph{$}. +@node cpu_models +@section CPU models + +@include docs/qemu-cpu-models.texi + @node disk_images @section Disk Images @@ -937,7 +943,7 @@ for details Bulk-only transport storage device, see @url{https://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} +@item usb-mtp,rootdir=@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} @@ -1097,7 +1103,9 @@ support provides a secure session, but no authentication. This allows any client to connect, and provides an encrypted session. @example -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] \ + -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \ + -vnc :1,tls-creds=tls0 -monitor stdio @end example In the above example @code{/etc/pki/qemu} should contain at least three files, @@ -1112,10 +1120,14 @@ 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. +in an environment with a private internal certificate authority. It uses the +same syntax as previously, but with @code{verify-peer} set to @code{yes} +instead. @example -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] \ + -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \ + -vnc :1,tls-creds=tls0 -monitor stdio @end example @@ -1126,7 +1138,9 @@ Finally, the previous method can be combined with VNC password authentication to provide two layers of authentication for clients. @example -qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio +qemu-system-i386 [...OPTIONS...] \ + -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \ + -vnc :1,tls-creds=tls0,password -monitor stdio (qemu) change vnc password Password: ******** (qemu) @@ -1163,7 +1177,9 @@ credentials. This can be enabled, by combining the 'sasl' option with the aforementioned TLS + x509 options: @example -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio +qemu-system-i386 [...OPTIONS...] \ + -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \ + -vnc :1,tls-creds=tls0,sasl -monitor stdio @end example @node vnc_setup_sasl @@ -1262,6 +1278,7 @@ The recommendation is for the server to keep its certificates in either * tls_generate_server:: * tls_generate_client:: * tls_creds_setup:: +* tls_psk:: @end menu @node tls_generate_ca @subsection Setup the Certificate Authority @@ -1510,6 +1527,42 @@ example with VNC: $QEMU -vnc 0.0.0.0:0,tls-creds=tls0 @end example +@node tls_psk +@subsection TLS Pre-Shared Keys (PSK) + +Instead of using certificates, you may also use TLS Pre-Shared Keys +(TLS-PSK). This can be simpler to set up than certificates but is +less scalable. + +Use the GnuTLS @code{psktool} program to generate a @code{keys.psk} +file containing one or more usernames and random keys: + +@example +mkdir -m 0700 /tmp/keys +psktool -u rich -p /tmp/keys/keys.psk +@end example + +TLS-enabled servers such as qemu-nbd can use this directory like so: + +@example +qemu-nbd \ + -t -x / \ + --object tls-creds-psk,id=tls0,endpoint=server,dir=/tmp/keys \ + --tls-creds tls0 \ + image.qcow2 +@end example + +When connecting from a qemu-based client you must specify the +directory containing @code{keys.psk} and an optional @var{username} +(defaults to ``qemu''): + +@example +qemu-img info \ + --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \ + --image-opts \ + file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/ +@end example + @node gdb_usage @section GDB usage @@ -2656,8 +2709,17 @@ The binary format is detected automatically. @command{qemu-microblaze} TODO. @cindex user mode (MIPS) -@command{qemu-mips} TODO. -@command{qemu-mipsel} TODO. +@command{qemu-mips} executes 32-bit big endian MIPS binaries (MIPS O32 ABI). + +@command{qemu-mipsel} executes 32-bit little endian MIPS binaries (MIPS O32 ABI). + +@command{qemu-mips64} executes 64-bit big endian MIPS binaries (MIPS N64 ABI). + +@command{qemu-mips64el} executes 64-bit little endian MIPS binaries (MIPS N64 ABI). + +@command{qemu-mipsn32} executes 32-bit big endian MIPS binaries (MIPS N32 ABI). + +@command{qemu-mipsn32el} executes 32-bit little endian MIPS binaries (MIPS N32 ABI). @cindex user mode (NiosII) @command{qemu-nios2} TODO. @@ -2754,209 +2816,7 @@ Run the emulation in single step mode. @include qemu-tech.texi -@node Deprecated features -@appendix Deprecated features - -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. - -@section Build options - -@subsection GTK 2.x - -Previously QEMU has supported building against both GTK 2.x -and 3.x series APIs. Support for the GTK 2.x builds will be -discontinued, so maintainers should switch to using GTK 3.x, -which is the default. - -@subsection SDL 1.2 - -Previously QEMU has supported building against both SDL 1.2 -and 2.0 series APIs. Support for the SDL 1.2 builds will be -discontinued, so maintainers should switch to using SDL 2.0, -which is the default. - -@section System emulator command line arguments - -@subsection -no-kvm (since 1.3.0) - -The ``-no-kvm'' argument is now a synonym for setting -``-machine accel=tcg''. - -@subsection -vnc tls (since 2.5.0) - -The ``-vnc tls'' argument is now a synonym for setting -``-object tls-creds-anon,id=tls0'' combined with -``-vnc tls-creds=tls0' - -@subsection -vnc x509 (since 2.5.0) - -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' - -@subsection -vnc x509verify (since 2.5.0) - -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' - -@subsection -tftp (since 2.6.0) - -The ``-tftp /some/dir'' argument is replaced by either -``-netdev user,id=x,tftp=/some/dir '' (for pluggable NICs, accompanied -with ``-device ...,netdev=x''), or ``-nic user,tftp=/some/dir'' -(for embedded NICs). The new syntax allows different settings to be -provided per NIC. - -@subsection -bootp (since 2.6.0) - -The ``-bootp /some/file'' argument is replaced by either -``-netdev user,id=x,bootp=/some/file '' (for pluggable NICs, accompanied -with ``-device ...,netdev=x''), or ``-nic user,bootp=/some/file'' -(for embedded NICs). The new syntax allows different settings to be -provided per NIC. - -@subsection -redir (since 2.6.0) - -The ``-redir [tcp|udp]:hostport:[guestaddr]:guestport'' argument is -replaced by either -``-netdev user,id=x,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport'' -(for pluggable NICs, accompanied with ``-device ...,netdev=x'') or -``-nic user,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport'' -(for embedded NICs). The new syntax allows different settings to be -provided per NIC. - -@subsection -smb (since 2.6.0) - -The ``-smb /some/dir'' argument is replaced by either -``-netdev user,id=x,smb=/some/dir '' (for pluggable NICs, accompanied -with ``-device ...,netdev=x''), or ``-nic user,smb=/some/dir'' -(for embedded NICs). The new syntax allows different settings to be -provided per NIC. - -@subsection -usbdevice (since 2.10.0) - -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. - -@subsection -nodefconfig (since 2.11.0) - -The ``-nodefconfig`` argument is a synonym for ``-no-user-config``. - -@subsection -balloon (since 2.12.0) - -The @option{--balloon virtio} argument has been superseded by -@option{--device virtio-balloon}. - -@subsection -machine s390-squash-mcss=on|off (since 2.12.0) - -The ``s390-squash-mcss=on`` property has been obsoleted by allowing the -cssid to be chosen freely. Instead of squashing subchannels into the -default channel subsystem image for guests that do not support multiple -channel subsystems, all devices can be put into the default channel -subsystem image. - -@subsection -fsdev handle (since 2.12.0) - -The ``handle'' fsdev backend does not support symlinks and causes the 9p -filesystem in the guest to fail a fair amount of tests from the PJD POSIX -filesystem test suite. Also it requires the CAP_DAC_READ_SEARCH capability, -which is not the recommended way to run QEMU. This backend should not be -used and it will be removed with no replacement. - -@subsection -no-frame (since 2.12.0) - -The @code{--no-frame} argument works with SDL 1.2 only. The other user -interfaces never implemented this in the first place. So this will be -removed together with SDL 1.2 support. - -@subsection -rtc-td-hack (since 2.12.0) - -The @code{-rtc-td-hack} option has been replaced by -@code{-rtc driftfix=slew}. - -@subsection -localtime (since 2.12.0) - -The @code{-localtime} option has been replaced by @code{-rtc base=localtime}. - -@subsection -startdate (since 2.12.0) - -The @code{-startdate} option has been replaced by @code{-rtc base=@var{date}}. - -@subsection -virtioconsole (since 3.0.0) - -Option @option{-virtioconsole} has been replaced by -@option{-device virtconsole}. - -@subsection -clock (since 3.0.0) - -The @code{-clock} option is ignored since QEMU version 1.7.0. There is no -replacement since it is not needed anymore. - -@section QEMU Machine Protocol (QMP) commands - -@subsection block-dirty-bitmap-add "autoload" parameter (since 2.12.0) - -"autoload" parameter is now ignored. All bitmaps are automatically loaded -from qcow2 images. - -@subsection query-cpus (since 2.12.0) - -The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command. - -@subsection query-cpus-fast "arch" output member (since 3.0.0) - -The ``arch'' output member of the ``query-cpus-fast'' command is -replaced by the ``target'' output member. - -@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 Page size support < 4k for embedded PowerPC CPUs (since 2.12.0) - -qemu-system-ppcemb will be removed. qemu-system-ppc (or qemu-system-ppc64) -should be used instead. That means that embedded 4xx PowerPC CPUs will not -support page sizes < 4096 any longer. - -@section System emulator machines - -@section Device options - -@subsection Block device options - -@subsubsection "backing": "" (since 2.12.0) - -In order to prevent QEMU from automatically opening an image's backing -chain, use ``"backing": null'' instead. - -@subsection vio-spapr-device device options - -@subsubsection "irq": "" (since 3.0.0) - -The ``irq'' property is obsoleted. +@include qemu-deprecated.texi @node Supported build platforms @appendix Supported build platforms