X-Git-Url: https://repo.jachan.dev/qemu.git/blobdiff_plain/685a4eaf6d552762e03ce02b136978e0e5d5a0c2..776d1344bd0566f412d5bc063e753a6b98530bcf:/qemu-doc.texi diff --git a/qemu-doc.texi b/qemu-doc.texi index 137f5814a8..0e0e0ae72b 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -39,6 +39,7 @@ * QEMU User space emulator:: * Implementation notes:: * Deprecated features:: +* Supported build platforms:: * License:: * Index:: @end menu @@ -140,6 +141,7 @@ accelerator is required to use more than one host CPU for emulation. * direct_linux_boot:: Direct Linux Boot * pcsys_usb:: USB emulation * vnc_security:: VNC security +* network_tls:: TLS setup for network services * gdb_usage:: GDB usage * pcsys_os_specific:: Target OS specific information @end menu @@ -713,20 +715,12 @@ state is not saved or restored properly (in particular USB). @node pcsys_network @section Network emulation -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. - -@subsection VLANs - -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). +QEMU can simulate several network cards (e.g. PCI or ISA cards on the PC +target) and can connect them to a network backend on the host or an emulated +hub. The various host network backends can either be used to connect the NIC of +the guest to a real network (e.g. by using a TAP devices or the non-privileged +user mode network stack), or to other guest instances running in another QEMU +process (e.g. by using the socket host network backend). @subsection Using TAP network interfaces @@ -762,7 +756,7 @@ network). The virtual network configuration is the following: @example - QEMU VLAN <------> Firewall/DHCP server <-----> Internet + guest (10.0.2.15) <------> Firewall/DHCP server <-----> Internet | (10.0.2.2) | ----> DNS server (10.0.2.3) @@ -797,11 +791,23 @@ When using the @option{'-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. -@subsection Connecting VLANs between QEMU instances +@subsection Hubs + +QEMU can simulate several hubs. A hub can be thought of 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). You can connect +guest NICs or host network backends to such a hub using the @option{-netdev +hubport} or @option{-nic hubport} options. The legacy @option{-net} option +also connects the given device to the emulated hub with ID 0 (i.e. the default +hub) unless you specify a netdev with @option{-net nic,netdev=xxx} here. -Using the @option{-net socket} option, it is possible to make VLANs -that span several QEMU instances. See @ref{sec_invocation} to have a -basic example. +@subsection Connecting emulated networks between QEMU instances + +Using the @option{-netdev socket} (or @option{-nic socket} or +@option{-net socket}) option, it is possible to create emulated +networks that span several QEMU instances. +See the description of the @option{-netdev socket} option in the +@ref{sec_invocation,,Invocation chapter} to have a basic example. @node pcsys_other_devs @section Other Devices @@ -1041,7 +1047,6 @@ considerations depending on the deployment scenarios. * vnc_sec_certificate_pw:: * vnc_sec_sasl:: * vnc_sec_certificate_sasl:: -* vnc_generate_cert:: * vnc_setup_sasl:: @end menu @node vnc_sec_none @@ -1161,25 +1166,105 @@ with the aforementioned TLS + x509 options: qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio @end example +@node vnc_setup_sasl + +@subsection Configuring SASL mechanisms + +The following documentation assumes use of the Cyrus SASL implementation on a +Linux host, but the principles should apply to any other SASL implementation +or host. 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 file. + +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: gssapi +keytab: /etc/qemu/krb5.tab +@end example + +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. + +When using TLS, if username+password authentication is desired, then a +reasonable configuration is + +@example +mech_list: scram-sha-1 +sasldb_path: /etc/qemu/passwd.db +@end example + +The @code{saslpasswd2} program can be used to populate the @code{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. -@node vnc_generate_cert -@subsection Generating certificates for VNC -The GNU TLS packages provides a command called @code{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 @code{/etc/pki/qemu} or for -unprivileged users in @code{$HOME/.pki/qemu}. +@node network_tls +@section TLS setup for network services + +Almost all network services in QEMU have the ability to use TLS for +session data encryption, along with x509 certificates for simple +client authentication. What follows is a description of how to +generate certificates suitable for usage with QEMU, and applies to +the VNC server, character devices with the TCP backend, NBD server +and client, and migration server and client. + +At a high level, QEMU requires certificates and private keys to be +provided in PEM format. Aside from the core fields, the certificates +should include various extension data sets, including v3 basic +constraints data, key purpose, key usage and subject alt name. + +The GnuTLS package includes a command called @code{certtool} which can +be used to easily generate certificates and keys in the required format +with expected data present. Alternatively a certificate management +service may be used. + +At a minimum it is necessary to setup a certificate authority, and +issue certificates to each server. If using x509 certificates for +authentication, then each client will also need to be issued a +certificate. + +Assuming that the QEMU network services will only ever be exposed to +clients on a private intranet, there is no need to use a commercial +certificate authority to create certificates. A self-signed CA is +sufficient, and in fact likely to be more secure since it removes +the ability of malicious 3rd parties to trick the CA into mis-issuing +certs for impersonating your services. The only likely exception +where a commercial CA might be desirable is if enabling the VNC +websockets server and exposing it directly to remote browser clients. +In such a case it might be useful to use a commercial CA to avoid +needing to install custom CA certs in the web browsers. + +The recommendation is for the server to keep its certificates in either +@code{/etc/pki/qemu} or for unprivileged users in @code{$HOME/.pki/qemu}. @menu -* vnc_generate_ca:: -* vnc_generate_server:: -* vnc_generate_client:: +* tls_generate_ca:: +* tls_generate_server:: +* tls_generate_client:: +* tls_creds_setup:: @end menu -@node vnc_generate_ca -@subsubsection Setup the Certificate Authority +@node tls_generate_ca +@subsection Setup the Certificate Authority 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 @@ -1190,11 +1275,10 @@ issued with it is lost. # certtool --generate-privkey > ca-key.pem @end example -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. - +To generate a self-signed certificate requires one core piece of information, +the name of the organization. A template file @code{ca.info} should be +populated with the desired data to avoid having to deal with interactive +prompts from certtool: @example # cat > ca.info < server.info < server-hostNNN.info < server-key.pem +# certtool --generate-privkey > server-hostNNN-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 + --load-privkey server-hostNNN-key.pem \ + --template server-hostNNN.info \ + --outfile server-hostNNN-cert.pem @end example -The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied -to the server for which they were generated. The @code{server-key.pem} is security -sensitive and should be kept protected with file mode 0600 to prevent disclosure. +The @code{dns_name} and @code{ip_address} fields in the template are setting +the subject alt name extension data. The @code{tls_www_server} keyword is the +key purpose extension to indicate this certificate is intended for usage in +a web server. Although QEMU network services are not in fact HTTP servers +(except for VNC websockets), setting this key purpose is still recommended. +The @code{encryption_key} and @code{signing_key} keyword is the key usage +extension to indicate this certificate is intended for usage in the data +session. + +The @code{server-hostNNN-key.pem} and @code{server-hostNNN-cert.pem} files +should now be securely copied to the server for which they were generated, +and renamed to @code{server-key.pem} and @code{server-cert.pem} when added +to the @code{/etc/pki/qemu} directory on the target host. The @code{server-key.pem} +file is security sensitive and should be kept protected with file mode 0600 +to prevent disclosure. -@node vnc_generate_client -@subsubsection Issuing client certificates +@node tls_generate_client +@subsection Issuing client certificates + +The QEMU x509 TLS credential setup defaults to enabling client verification +using certificates, providing a simple authentication mechanism. If this +default is used, each client also needs to be issued a certificate. The client +certificate contains enough metadata to uniquely identify the client with the +scope of the certificate authority. The client certificate would typically +include fields for organization, state, city, building, etc. + +Once again on the host holding the CA, create template files containing the +information for each client, and use it to issue client certificates. -If the QEMU VNC server is to use the @code{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: @example -# cat > client.info < client-hostNNN.info < client-hostNNN-key.pem +# certtool --generate-certificate \ + --load-ca-certificate ca-cert.pem \ + --load-ca-privkey ca-key.pem \ + --load-privkey client-hostNNN-key.pem \ + --template client-hostNNN.info \ + --outfile client-hostNNN-cert.pem +@end example + +The subject alt name extension data is not required for clients, so the +the @code{dns_name} and @code{ip_address} fields are not included. +The @code{tls_www_client} keyword is the key purpose extension to indicate +this certificate is intended for usage in a web client. Although QEMU +network clients are not in fact HTTP clients, setting this key purpose is +still recommended. The @code{encryption_key} and @code{signing_key} keyword +is the key usage extension to indicate this certificate is intended for +usage in the data session. + +The @code{client-hostNNN-key.pem} and @code{client-hostNNN-cert.pem} files +should now be securely copied to the client for which they were generated, +and renamed to @code{client-key.pem} and @code{client-cert.pem} when added +to the @code{/etc/pki/qemu} directory on the target host. The @code{client-key.pem} +file is security sensitive and should be kept protected with file mode 0600 +to prevent disclosure. + +If a single host is going to be using TLS in both a client and server +role, it is possible to create a single certificate to cover both roles. +This would be quite common for the migration and NBD services, where a +QEMU process will be started by accepting a TLS protected incoming migration, +and later itself be migrated out to another host. To generate a single +certificate, simply include the template data from both the client and server +instructions in one. + +@example +# cat > both-hostNNN.info < client-key.pem +# certtool --generate-privkey > both-hostNNN-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 + --load-privkey both-hostNNN-key.pem \ + --template both-hostNNN.info \ + --outfile both-hostNNN-cert.pem @end example -The @code{client-key.pem} and @code{client-cert.pem} files should now be securely -copied to the client for which they were generated. +When copying the PEM files to the target host, save them twice, +once as @code{server-cert.pem} and @code{server-key.pem}, and +again as @code{client-cert.pem} and @code{client-key.pem}. +@node tls_creds_setup +@subsection TLS x509 credential configuration -@node vnc_setup_sasl +QEMU has a standard mechanism for loading x509 credentials that will be +used for network services and clients. It requires specifying the +@code{tls-creds-x509} class name to the @code{--object} command line +argument for the system emulators. Each set of credentials loaded should +be given a unique string identifier via the @code{id} parameter. A single +set of TLS credentials can be used for multiple network backends, so VNC, +migration, NBD, character devices can all share the same credentials. Note, +however, that credentials for use in a client endpoint must be loaded +separately from those used in a server endpoint. -@subsection Configuring SASL mechanisms +When specifying the object, the @code{dir} parameters specifies which +directory contains the credential files. This directory is expected to +contain files with the names mentioned previously, @code{ca-cert.pem}, +@code{server-key.pem}, @code{server-cert.pem}, @code{client-key.pem} +and @code{client-cert.pem} as appropriate. It is also possible to +include a set of pre-generated Diffie-Hellman (DH) parameters in a file +@code{dh-params.pem}, which can be created using the +@code{certtool --generate-dh-params} command. If omitted, QEMU will +dynamically generate DH parameters when loading the credentials. -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. +The @code{endpoint} parameter indicates whether the credentials will +be used for a network client or server, and determines which PEM +files are loaded. -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. +The @code{verify} parameter determines whether x509 certificate +validation should be performed. This defaults to enabled, meaning +clients will always validate the server hostname against the +certificate subject alt name fields and/or CN field. It also +means that servers will request that clients provide a certificate +and validate them. Verification should never be turned off for +client endpoints, however, it may be turned off for server endpoints +if an alternative mechanism is used to authenticate clients. For +example, the VNC server can use SASL to authenticate clients +instead. -When not using TLS the recommended configuration is +To load server credentials with client certificate validation +enabled @example -mech_list: gssapi -keytab: /etc/qemu/krb5.tab +$QEMU -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server @end example -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. - -When using TLS, if username+password authentication is desired, then a -reasonable configuration is +while to load client credentials use @example -mech_list: scram-sha-1 -sasldb_path: /etc/qemu/passwd.db +$QEMU -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client @end example -The saslpasswd2 program can be used to populate the passwd.db file with -accounts. +Network services which support TLS will all have a @code{tls-creds} +parameter which expects the ID of the TLS credentials object. For +example with VNC: -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. +@example +$QEMU -vnc 0.0.0.0:0,tls-creds=tls0 +@end example @node gdb_usage @section GDB usage @@ -2606,37 +2791,11 @@ which is the default. @section System emulator command line arguments -@subsection -tdf (since 1.3.0) - -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''. - -@subsection -no-kvm-pit-reinjection (since 1.3.0) - -The ``-no-kvm-pit-reinjection'' argument is now a -synonym for setting ``-global kvm-pit.lost_tick_policy=discard''. - -@subsection -no-kvm-irqchip (since 1.3.0) - -The ``-no-kvm-irqchip'' argument is now a synonym for -setting ``-machine kernel_irqchip=off''. - @subsection -no-kvm (since 1.3.0) The ``-no-kvm'' argument is now a synonym for setting ``-machine accel=tcg''. -@subsection -mon default=on (since 2.4.0) - -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. - @subsection -vnc tls (since 2.5.0) The ``-vnc tls'' argument is now a synonym for setting @@ -2659,48 +2818,38 @@ combined with ``-vnc tls-creds=tls0' @subsection -tftp (since 2.6.0) -The ``-tftp /some/dir'' argument is replaced by -``-netdev user,id=x,tftp=/some/dir'', either accompanied with -``-device ...,netdev=x'' (for pluggable NICs) or ``-net nic,netdev=x'' +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 -``-netdev user,id=x,bootp=/some/file'', either accompanied with -``-device ...,netdev=x'' (for pluggable NICs) or ``-net nic,netdev=x'' +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 ``-netdev -user,id=x,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport'', -either accompanied with ``-device ...,netdev=x'' (for pluggable NICs) or -``-net nic,netdev=x'' (for embedded NICs). The new syntax allows different -settings to be provided per NIC. +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 -``-netdev user,id=x,smb=/some/dir'', either accompanied with -``-device ...,netdev=x'' (for pluggable NICs) or ``-net nic,netdev=x'' +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 -net vlan (since 2.9.0) - -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. - -@subsection -drive if=scsi (since 2.9.0) - -The ``-drive if=scsi'' argument is replaced by the the -``-device BUS-TYPE'' argument combined with ``-drive if=none''. - @subsection -drive cyls=...,heads=...,secs=...,trans=... (since 2.10.0) The drive geometry arguments are replaced by the the geometry arguments @@ -2716,12 +2865,6 @@ that can be specified with the ``-device'' parameter. The drive addr argument is replaced by the the addr argument that can be specified with the ``-device'' parameter. -@subsection -net dump (since 2.10.0) - -The ``--net dump'' argument is now replaced with the -``-object filter-dump'' argument which works in combination -with the modern ``-netdev`` backends instead. - @subsection -usbdevice (since 2.10.0) The ``-usbdevice DEV'' argument is now a synonym for setting @@ -2734,6 +2877,11 @@ enabled via the ``-machine usb=on'' argument. 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 @@ -2750,6 +2898,30 @@ 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 2.13.0) + +Option @option{-virtioconsole} has been replaced by +@option{-device virtconsole}. + @section qemu-img command line arguments @subsection convert -s (since 2.0.0) @@ -2764,15 +2936,14 @@ by the ``convert -l snapshot_param'' argument instead. "autoload" parameter is now ignored. All bitmaps are automatically loaded from qcow2 images. -@section System emulator human monitor commands +@subsection query-cpus (since 2.12.0) -@subsection host_net_add (since 2.10.0) +The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command. -The ``host_net_add'' command is replaced by the ``netdev_add'' command. +@subsection query-cpus-fast "arch" output member (since 2.13.0) -@subsection host_net_remove (since 2.10.0) - -The ``host_net_remove'' command is replaced by the ``netdev_del'' command. +The ``arch'' output member of the ``query-cpus-fast'' command is +replaced by the ``target'' output member. @section System emulator devices @@ -2794,6 +2965,80 @@ support page sizes < 4096 any longer. The ``xlnx-ep108'' machine has been replaced by the ``xlnx-zcu102'' machine. The ``xlnx-zcu102'' machine has the same features and capabilites in QEMU. +@section Block device options + +@subsection "backing": "" (since 2.12.0) + +In order to prevent QEMU from automatically opening an image's backing +chain, use ``"backing": null'' instead. + +@node Supported build platforms +@appendix Supported build platforms + +QEMU aims to support building and executing on multiple host OS platforms. +This appendix outlines which platforms are the major build targets. These +platforms are used as the basis for deciding upon the minimum required +versions of 3rd party software QEMU depends on. The supported platforms +are the targets for automated testing performed by the project when patches +are submitted for review, and tested before and after merge. + +If a platform is not listed here, it does not imply that QEMU won't work. +If an unlisted platform has comparable software versions to a listed platform, +there is every expectation that it will work. Bug reports are welcome for +problems encountered on unlisted platforms unless they are clearly older +vintage than what is described here. + +Note that when considering software versions shipped in distros as support +targets, QEMU considers only the version number, and assumes the features in +that distro match the upstream release with the same version. In other words, +if a distro backports extra features to the software in their distro, QEMU +upstream code will not add explicit support for those backports, unless the +feature is auto-detectable in a manner that works for the upstream releases +too. + +The Repology site @url{https://repology.org} is a useful resource to identify +currently shipped versions of software in various operating systems, though +it does not cover all distros listed below. + +@section Linux OS + +For distributions with frequent, short-lifetime releases, the project will +aim to support all versions that are not end of life by their respective +vendors. For the purposes of identifying supported software versions, the +project will look at Fedora, Ubuntu, and openSUSE distros. Other short- +lifetime distros will be assumed to ship similar software versions. + +For distributions with long-lifetime releases, the project will aim to support +the most recent major version at all times. Support for the previous major +version will be dropped 2 years after the new major version is released. For +the purposes of identifying supported software versions, the project will look +at RHEL, Debian, Ubuntu LTS, and SLES distros. Other long-lifetime distros will +be assumed to ship similar software versions. + +@section Windows + +The project supports building with current versions of the MinGW toolchain, +hosted on Linux. + +@section macOS + +The project supports building with the two most recent versions of macOS, with +the current homebrew package set available. + +@section FreeBSD + +The project aims to support the all the versions which are not end of life. + +@section NetBSD + +The project aims to support the most recent major version at all times. Support +for the previous major version will be dropped 2 years after the new major +version is released. + +@section OpenBSD + +The project aims to support the all the versions which are not end of life. + @node License @appendix License