Revert "block: Remove deprecated -drive option addr"

[qemu.git] / qemu-doc.texi

diff --git a/qemu-doc.texi b/qemu-doc.texi
index 9216848af736f3960139637c6bc18e9177127930..ae5531a053fbba1b64a42e4a02735fc5bb680384 100644 (file)
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -39,6 +39,7 @@
 * QEMU User space emulator::
 * Implementation notes::
 * Deprecated features::
 * QEMU User space emulator::
 * Implementation notes::
 * Deprecated features::

+* Supported build platforms::

 * License::
 * Index::
 @end menu
 * License::
 * Index::
 @end menu


@@ -714,20 +715,12 @@ state is not saved or restored properly (in particular USB).
 @node pcsys_network
 @section Network emulation
 
 @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
 
 
 @subsection Using TAP network interfaces
 


@@ -763,7 +756,7 @@ network). The virtual network configuration is the following:
 
 @example
 
 
 @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)
                            |          (10.0.2.2)
                            |
                            ---->  DNS server (10.0.2.3)


@@ -798,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.
 
 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.
+
+@subsection Connecting emulated networks between QEMU instances

 
 

-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.
+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
 
 @node pcsys_other_devs
 @section Other Devices


@@ -1257,6 +1262,7 @@ The recommendation is for the server to keep its certificates in either
 * tls_generate_server::
 * tls_generate_client::
 * tls_creds_setup::
 * tls_generate_server::
 * tls_generate_client::
 * tls_creds_setup::

+* tls_psk::

 @end menu
 @node tls_generate_ca
 @subsection Setup the Certificate Authority
 @end menu
 @node tls_generate_ca
 @subsection Setup the Certificate Authority


@@ -1505,6 +1511,42 @@ example with VNC:
 $QEMU -vnc 0.0.0.0:0,tls-creds=tls0
 @end example
 
 $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
 
 @node gdb_usage
 @section GDB usage
 


@@ -2786,16 +2828,6 @@ which is the default.
 
 @section System emulator command line arguments
 
 
 @section System emulator command line arguments
 

-@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
 @subsection -no-kvm (since 1.3.0)
 
 The ``-no-kvm'' argument is now a synonym for setting


@@ -2855,11 +2887,6 @@ with ``-device ...,netdev=x''), or ``-nic user,smb=/some/dir''
 (for embedded NICs). The new syntax allows different settings to be
 provided per NIC.
 
 (for embedded NICs). The new syntax allows different settings to be
 provided per NIC.
 

-@subsection -drive cyls=...,heads=...,secs=...,trans=... (since 2.10.0)
-
-The drive geometry arguments are replaced by the the geometry arguments
-that can be specified with the ``-device'' parameter.
-

 @subsection -drive serial=... (since 2.10.0)
 
 The drive serial argument is replaced by the the serial argument
 @subsection -drive serial=... (since 2.10.0)
 
 The drive serial argument is replaced by the the serial argument


@@ -2922,12 +2949,20 @@ The @code{-localtime} option has been replaced by @code{-rtc base=localtime}.
 
 The @code{-startdate} option has been replaced by @code{-rtc base=@var{date}}.
 
 
 The @code{-startdate} option has been replaced by @code{-rtc base=@var{date}}.
 

-@section qemu-img command line arguments
+@subsection -virtioconsole (since 3.0.0)

 
 

-@subsection convert -s (since 2.0.0)
+Option @option{-virtioconsole} has been replaced by
+@option{-device virtconsole}.

 
 

-The ``convert -s snapshot_id_or_name'' argument is obsoleted
-by the ``convert -l snapshot_param'' argument instead.
+@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.
+
+@subsection -enable-hax (since 3.0.0)
+
+The @option{-enable-hax} option has been replaced by @option{-accel hax}.
+Both options have been introduced in QEMU version 2.9.0.

 
 @section QEMU Machine Protocol (QMP) commands
 
 
 @section QEMU Machine Protocol (QMP) commands
 


@@ -2940,7 +2975,7 @@ from qcow2 images.
 
 The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
 
 
 The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
 

-@subsection query-cpus-fast "arch" output member (since 2.13.0)
+@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.
 
 The ``arch'' output member of the ``query-cpus-fast'' command is
 replaced by the ``target'' output member.


@@ -2960,18 +2995,93 @@ support page sizes < 4096 any longer.
 
 @section System emulator machines
 
 
 @section System emulator machines
 

-@subsection Xilinx EP108 (since 2.11.0)
+@subsection pc-0.10 and pc-0.11 (since 3.0)
+
+These machine types are very old and likely can not be used for live migration
+from old QEMU versions anymore. A newer machine type should be used instead.

 
 

-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 Device options

 
 

-@section Block device options
+@subsection Block device options

 
 

-@subsection "backing": "" (since 2.12.0)
+@subsubsection "backing": "" (since 2.12.0)

 
 In order to prevent QEMU from automatically opening an image's backing
 chain, use ``"backing": null'' instead.
 
 
 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.
+
+@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
 
 @node License
 @appendix License