Merge remote-tracking branch 'remotes/pmaydell/tags/pull-docs-20200306' into staging

docs:
 * Convert qemu-doc from Texinfo to rST

# gpg: Signature made Fri 06 Mar 2020 11:08:15 GMT
# gpg:                using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg:                issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@gmail.com>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83  15CF 3C25 25ED 1436 0CDE

* remotes/pmaydell/tags/pull-docs-20200306: (33 commits)
  *.hx: Remove all the STEXI/ETEXI blocks
  docs: Remove old texinfo sources
  docs: Stop building qemu-doc
  ui/cocoa.m: Update documentation file and pathname
  docs: Generate qemu.1 manpage with Sphinx
  docs: Split out sections for the manpage into .rst.inc files
  qemu-options.hx: Fix up the autogenerated rST
  qemu-options.hx: Add rST documentation fragments
  scripts/hxtool-conv: Archive script used in qemu-options.hx conversion
  docs: Roll -prom-env and -g target-specific info into qemu-options.hx
  docs: Roll semihosting option information into qemu-options.hx
  doc/scripts/hxtool.py: Strip trailing ':' from DEFHEADING/ARCHHEADING
  hmp-commands-info.hx: Add rST documentation fragments
  hmp-commands.hx: Add rST documentation fragments
  docs/system: convert Texinfo documentation to rST
  docs/system: convert the documentation of deprecated features to rST.
  docs/system: convert managed startup to rST.
  docs/system: Convert security.texi to rST format
  docs/system: Convert qemu-cpu-models.texi to rST
  docs: Create defs.rst.inc as a place to define substitutions
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

39 files changed, 4298 insertions, 980 deletions

diff --git a/docs/system/build-platforms.rst b/docs/system/build-platforms.rst
new file mode 100644
index 0000000000..c2b92a9698
--- /dev/null
+++ b/docs/system/build-platforms.rst
@@ -0,0 +1,79 @@
+.. _Supported-build-platforms:
+
+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 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.
+
+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, or when it reaches "end of life". 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.
+
+Windows
+-------
+
+The project supports building with current versions of the MinGW
+toolchain, hosted on Linux.
+
+macOS
+-----
+
+The project supports building with the two most recent versions of
+macOS, with the current homebrew package set available.
+
+FreeBSD
+-------
+
+The project aims to support the all the versions which are not end of
+life.
+
+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.
+
+OpenBSD
+-------
+
+The project aims to support the all the versions which are not end of
+life.
diff --git a/docs/system/conf.py b/docs/system/conf.py
index 7ca115f5e0..6251849fef 100644
--- a/docs/system/conf.py
+++ b/docs/system/conf.py
@@ -13,10 +13,16 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
 # This slightly misuses the 'description', but is the best way to get
 # the manual title to appear in the sidebar.
 html_theme_options['description'] = u'System Emulation User''s Guide'
+
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
+    ('qemu-manpage', 'qemu', u'QEMU User Documentation',
+     ['Fabrice Bellard'], 1),
     ('qemu-block-drivers', 'qemu-block-drivers',
      u'QEMU block drivers reference',
-     ['Fabrice Bellard and the QEMU Project developers'], 7)
+     ['Fabrice Bellard and the QEMU Project developers'], 7),
+    ('qemu-cpu-models', 'qemu-cpu-models',
+     u'QEMU CPU Models',
+     ['The QEMU Project developers'], 7)
 ]
diff --git a/docs/system/cpu-models-mips.rst.inc b/docs/system/cpu-models-mips.rst.inc
new file mode 100644
index 0000000000..499b5b6fed
--- /dev/null
+++ b/docs/system/cpu-models-mips.rst.inc
@@ -0,0 +1,105 @@
+Supported CPU model configurations on MIPS hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+QEMU supports variety of MIPS CPU models:
+
+Supported CPU models for MIPS32 hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following CPU models are supported for use on MIPS32 hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+``mips32r6-generic``
+    MIPS32 Processor (Release 6, 2015)
+
+``P5600``
+    MIPS32 Processor (P5600, 2014)
+
+``M14K``, ``M14Kc``
+    MIPS32 Processor (M14K, 2009)
+
+``74Kf``
+    MIPS32 Processor (74K, 2007)
+
+``34Kf``
+    MIPS32 Processor (34K, 2006)
+
+``24Kc``, ``24KEc``, ``24Kf``
+    MIPS32 Processor (24K, 2003)
+
+``4Kc``, ``4Km``, ``4KEcR1``, ``4KEmR1``, ``4KEc``, ``4KEm``
+    MIPS32 Processor (4K, 1999)
+
+
+Supported CPU models for MIPS64 hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following CPU models are supported for use on MIPS64 hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+``I6400``
+    MIPS64 Processor (Release 6, 2014)
+
+``Loongson-2F``
+    MIPS64 Processor (Loongson 2, 2008)
+
+``Loongson-2E``
+    MIPS64 Processor (Loongson 2, 2006)
+
+``mips64dspr2``
+    MIPS64 Processor (Release 2, 2006)
+
+``MIPS64R2-generic``, ``5KEc``, ``5KEf``
+    MIPS64 Processor (Release 2, 2002)
+
+``20Kc``
+    MIPS64 Processor (20K, 2000
+
+``5Kc``, ``5Kf``
+    MIPS64 Processor (5K, 1999)
+
+``VR5432``
+    MIPS64 Processor (VR, 1998)
+
+``R4000``
+    MIPS64 Processor (MIPS III, 1991)
+
+
+Supported CPU models for nanoMIPS hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following CPU models are supported for use on nanoMIPS hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+``I7200``
+    MIPS I7200 (nanoMIPS, 2018)
+
+Preferred CPU models for MIPS hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following CPU models are preferred for use on different MIPS hosts:
+
+``MIPS III``
+    R4000
+
+``MIPS32R2``
+    34Kf
+
+``MIPS64R6``
+    I6400
+
+``nanoMIPS``
+    I7200
+
diff --git a/docs/system/cpu-models-x86.rst.inc b/docs/system/cpu-models-x86.rst.inc
new file mode 100644
index 0000000000..cbad930c70
--- /dev/null
+++ b/docs/system/cpu-models-x86.rst.inc
@@ -0,0 +1,365 @@
+Recommendations for KVM CPU model configuration on x86 hosts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The information that follows provides recommendations for configuring
+CPU models on x86 hosts. The goals are to maximise performance, while
+protecting guest OS against various CPU hardware flaws, and optionally
+enabling live migration between hosts with heterogeneous CPU models.
+
+
+Two ways to configure CPU models with QEMU / KVM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+(1) **Host passthrough**
+
+    This passes the host CPU model features, model, stepping, exactly to
+    the guest. Note that KVM may filter out some host CPU model features
+    if they cannot be supported with virtualization. Live migration is
+    unsafe when this mode is used as libvirt / QEMU cannot guarantee a
+    stable CPU is exposed to the guest across hosts. This is the
+    recommended CPU to use, provided live migration is not required.
+
+(2) **Named model**
+
+    QEMU comes with a number of predefined named CPU models, that
+    typically refer to specific generations of hardware released by
+    Intel and AMD.  These allow the guest VMs to have a degree of
+    isolation from the host CPU, allowing greater flexibility in live
+    migrating between hosts with differing hardware.  @end table
+
+In both cases, it is possible to optionally add or remove individual CPU
+features, to alter what is presented to the guest by default.
+
+Libvirt supports a third way to configure CPU models known as "Host
+model".  This uses the QEMU "Named model" feature, automatically picking
+a CPU model that is similar the host CPU, and then adding extra features
+to approximate the host model as closely as possible. This does not
+guarantee the CPU family, stepping, etc will precisely match the host
+CPU, as they would with "Host passthrough", but gives much of the
+benefit of passthrough, while making live migration safe.
+
+
+Preferred CPU models for Intel x86 hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following CPU models are preferred for use on Intel hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+``Skylake-Server``, ``Skylake-Server-IBRS``
+    Intel Xeon Processor (Skylake, 2016)
+
+``Skylake-Client``, ``Skylake-Client-IBRS``
+    Intel Core Processor (Skylake, 2015)
+
+``Broadwell``, ``Broadwell-IBRS``, ``Broadwell-noTSX``, ``Broadwell-noTSX-IBRS``
+    Intel Core Processor (Broadwell, 2014)
+
+``Haswell``, ``Haswell-IBRS``, ``Haswell-noTSX``, ``Haswell-noTSX-IBRS``
+    Intel Core Processor (Haswell, 2013)
+
+``IvyBridge``, ``IvyBridge-IBR``
+    Intel Xeon E3-12xx v2 (Ivy Bridge, 2012)
+
+``SandyBridge``, ``SandyBridge-IBRS``
+    Intel Xeon E312xx (Sandy Bridge, 2011)
+
+``Westmere``, ``Westmere-IBRS``
+    Westmere E56xx/L56xx/X56xx (Nehalem-C, 2010)
+
+``Nehalem``, ``Nehalem-IBRS``
+    Intel Core i7 9xx (Nehalem Class Core i7, 2008)
+
+``Penryn``
+    Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007)
+
+``Conroe``
+    Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006)
+
+
+Important CPU features for Intel x86 hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following are important CPU features that should be used on Intel
+x86 hosts, when available in the host CPU. Some of them require explicit
+configuration to enable, as they are not included by default in some, or
+all, of the named CPU models listed above. In general all of these
+features are included if using "Host passthrough" or "Host model".
+
+``pcid``
+  Recommended to mitigate the cost of the Meltdown (CVE-2017-5754) fix.
+
+  Included by default in Haswell, Broadwell & Skylake Intel CPU models.
+
+  Should be explicitly turned on for Westmere, SandyBridge, and
+  IvyBridge Intel CPU models. Note that some desktop/mobile Westmere
+  CPUs cannot support this feature.
+
+``spec-ctrl``
+  Required to enable the Spectre v2 (CVE-2017-5715) fix.
+
+  Included by default in Intel CPU models with -IBRS suffix.
+
+  Must be explicitly turned on for Intel CPU models without -IBRS
+  suffix.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+``stibp``
+  Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
+  operating systems.
+
+  Must be explicitly turned on for all Intel CPU models.
+
+  Requires the host CPU microcode to support this feature before it can
+  be used for guest CPUs.
+
+``ssbd``
+  Required to enable the CVE-2018-3639 fix.
+
+  Not included by default in any Intel CPU model.
+
+  Must be explicitly turned on for all Intel CPU models.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+``pdpe1gb``
+  Recommended to allow guest OS to use 1GB size pages.
+
+  Not included by default in any Intel CPU model.
+
+  Should be explicitly turned on for all Intel CPU models.
+
+  Note that not all CPU hardware will support this feature.
+
+``md-clear``
+  Required to confirm the MDS (CVE-2018-12126, CVE-2018-12127,
+  CVE-2018-12130, CVE-2019-11091) fixes.
+
+  Not included by default in any Intel CPU model.
+
+  Must be explicitly turned on for all Intel CPU models.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+
+Preferred CPU models for AMD x86 hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following CPU models are preferred for use on Intel hosts.
+Administrators / applications are recommended to use the CPU model that
+matches the generation of the host CPUs in use. In a deployment with a
+mixture of host CPU models between machines, if live migration
+compatibility is required, use the newest CPU model that is compatible
+across all desired hosts.
+
+``EPYC``, ``EPYC-IBPB``
+    AMD EPYC Processor (2017)
+
+``Opteron_G5``
+    AMD Opteron 63xx class CPU (2012)
+
+``Opteron_G4``
+    AMD Opteron 62xx class CPU (2011)
+
+``Opteron_G3``
+    AMD Opteron 23xx (Gen 3 Class Opteron, 2009)
+
+``Opteron_G2``
+    AMD Opteron 22xx (Gen 2 Class Opteron, 2006)
+
+``Opteron_G1``
+    AMD Opteron 240 (Gen 1 Class Opteron, 2004)
+
+
+Important CPU features for AMD x86 hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following are important CPU features that should be used on AMD x86
+hosts, when available in the host CPU. Some of them require explicit
+configuration to enable, as they are not included by default in some, or
+all, of the named CPU models listed above. In general all of these
+features are included if using "Host passthrough" or "Host model".
+
+``ibpb``
+  Required to enable the Spectre v2 (CVE-2017-5715) fix.
+
+  Included by default in AMD CPU models with -IBPB suffix.
+
+  Must be explicitly turned on for AMD CPU models without -IBPB suffix.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+``stibp``
+  Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
+  operating systems.
+
+  Must be explicitly turned on for all AMD CPU models.
+
+  Requires the host CPU microcode to support this feature before it
+  can be used for guest CPUs.
+
+``virt-ssbd``
+  Required to enable the CVE-2018-3639 fix
+
+  Not included by default in any AMD CPU model.
+
+  Must be explicitly turned on for all AMD CPU models.
+
+  This should be provided to guests, even if amd-ssbd is also provided,
+  for maximum guest compatibility.
+
+  Note for some QEMU / libvirt versions, this must be force enabled when
+  when using "Host model", because this is a virtual feature that
+  doesn't exist in the physical host CPUs.
+
+``amd-ssbd``
+  Required to enable the CVE-2018-3639 fix
+
+  Not included by default in any AMD CPU model.
+
+  Must be explicitly turned on for all AMD CPU models.
+
+  This provides higher performance than ``virt-ssbd`` so should be
+  exposed to guests whenever available in the host. ``virt-ssbd`` should
+  none the less also be exposed for maximum guest compatibility as some
+  kernels only know about ``virt-ssbd``.
+
+``amd-no-ssb``
+  Recommended to indicate the host is not vulnerable CVE-2018-3639
+
+  Not included by default in any AMD CPU model.
+
+  Future hardware generations of CPU will not be vulnerable to
+  CVE-2018-3639, and thus the guest should be told not to enable
+  its mitigations, by exposing amd-no-ssb. This is mutually
+  exclusive with virt-ssbd and amd-ssbd.
+
+``pdpe1gb``
+  Recommended to allow guest OS to use 1GB size pages
+
+  Not included by default in any AMD CPU model.
+
+  Should be explicitly turned on for all AMD CPU models.
+
+  Note that not all CPU hardware will support this feature.
+
+
+Default x86 CPU models
+^^^^^^^^^^^^^^^^^^^^^^
+
+The default QEMU CPU models are designed such that they can run on all
+hosts.  If an application does not wish to do perform any host
+compatibility checks before launching guests, the default is guaranteed
+to work.
+
+The default CPU models will, however, leave the guest OS vulnerable to
+various CPU hardware flaws, so their use is strongly discouraged.
+Applications should follow the earlier guidance to setup a better CPU
+configuration, with host passthrough recommended if live migration is
+not needed.
+
+``qemu32``, ``qemu64``
+    QEMU Virtual CPU version 2.5+ (32 & 64 bit variants)
+
+``qemu64`` is used for x86_64 guests and ``qemu32`` is used for i686
+guests, when no ``-cpu`` argument is given to QEMU, or no ``<cpu>`` is
+provided in libvirt XML.
+
+Other non-recommended x86 CPUs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following CPUs models are compatible with most AMD and Intel x86
+hosts, but their usage is discouraged, as they expose a very limited
+featureset, which prevents guests having optimal performance.
+
+``kvm32``, ``kvm64``
+    Common KVM processor (32 & 64 bit variants).
+
+    Legacy models just for historical compatibility with ancient QEMU
+    versions.
+
+``486``, ``athlon``, ``phenom``, ``coreduo``, ``core2duo``, ``n270``, ``pentium``, ``pentium2``, ``pentium3``
+    Various very old x86 CPU models, mostly predating the introduction
+    of hardware assisted virtualization, that should thus not be
+    required for running virtual machines.
+
+
+Syntax for configuring CPU models
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The examples below illustrate the approach to configuring the various
+CPU models / features in QEMU and libvirt.
+
+QEMU command line
+^^^^^^^^^^^^^^^^^
+
+Host passthrough:
+
+.. parsed-literal::
+
+  |qemu_system| -cpu host
+
+Host passthrough with feature customization:
+
+.. parsed-literal::
+
+  |qemu_system| -cpu host,-vmx,...
+
+Named CPU models:
+
+.. parsed-literal::
+
+  |qemu_system| -cpu Westmere
+
+Named CPU models with feature customization:
+
+.. parsed-literal::
+
+  |qemu_system| -cpu Westmere,+pcid,...
+
+Libvirt guest XML
+^^^^^^^^^^^^^^^^^
+
+Host passthrough::
+
+    <cpu mode='host-passthrough'/>
+
+Host passthrough with feature customization::
+
+    <cpu mode='host-passthrough'>
+        <feature name="vmx" policy="disable"/>
+        ...
+    </cpu>
+
+Host model::
+
+    <cpu mode='host-model'/>
+
+Host model with feature customization::
+
+    <cpu mode='host-model'>
+        <feature name="vmx" policy="disable"/>
+        ...
+    </cpu>
+
+Named model::
+
+    <cpu mode='custom'>
+        <model name="Westmere"/>
+    </cpu>
+
+Named model with feature customization::
+
+    <cpu mode='custom'>
+        <model name="Westmere"/>
+        <feature name="pcid" policy="require"/>
+        ...
+    </cpu>
diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
new file mode 100644
index 0000000000..1eaa559079
--- /dev/null
+++ b/docs/system/deprecated.rst
@@ -0,0 +1,446 @@
+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 section. 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.
+
+System emulator command line arguments
+--------------------------------------
+
+``-machine enforce-config-section=on|off`` (since 3.1)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``enforce-config-section`` parameter is replaced by the
+``-global migration.send-configuration={on|off}`` option.
+
+``-no-kvm`` (since 1.3.0)
+'''''''''''''''''''''''''
+
+The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``.
+
+``-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.
+
+``-drive file=json:{...{'driver':'file'}}`` (since 3.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The 'file' driver for drives is no longer appropriate for character or host
+devices and will only accept regular files (S_IFREG). The correct driver
+for these file types is 'host_cdrom' or 'host_device' as appropriate.
+
+``-net ...,name=``\ *name* (since 3.1)
+''''''''''''''''''''''''''''''''''''''
+
+The ``name`` parameter of the ``-net`` option is a synonym
+for the ``id`` parameter, which should now be used instead.
+
+``-smp`` (invalid topologies) (since 3.1)
+'''''''''''''''''''''''''''''''''''''''''
+
+CPU topology properties should describe whole machine topology including
+possible CPUs.
+
+However, historically it was possible to start QEMU with an incorrect topology
+where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
+which could lead to an incorrect topology enumeration by the guest.
+Support for invalid topologies will be removed, the user must ensure
+topologies described with -smp include all possible cpus, i.e.
+*sockets* * *cores* * *threads* = *maxcpus*.
+
+``-vnc acl`` (since 4.0.0)
+''''''''''''''''''''''''''
+
+The ``acl`` option to the ``-vnc`` argument has been replaced
+by the ``tls-authz`` and ``sasl-authz`` options.
+
+``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``-audiodev`` argument is now the preferred way to specify audio
+backend settings instead of environment variables.  To ease migration to
+the new format, the ``-audiodev-help`` option can be used to convert
+the current values of the environment variables to ``-audiodev`` options.
+
+Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+When not using the deprecated legacy audio config, each sound card
+should specify an ``audiodev=`` property.  Additionally, when using
+vnc, you should specify an ``audiodev=`` propery if you plan to
+transmit audio through the VNC protocol.
+
+``-mon ...,control=readline,pretty=on|off`` (since 4.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``pretty=on|off`` switch has no effect for HMP monitors, but is
+silently ignored. Using the switch with HMP monitors will become an
+error in the future.
+
+``-realtime`` (since 4.1)
+'''''''''''''''''''''''''
+
+The ``-realtime mlock=on|off`` argument has been replaced by the
+``-overcommit mem-lock=on|off`` argument.
+
+``-numa node,mem=``\ *size* (since 4.1)
+'''''''''''''''''''''''''''''''''''''''
+
+The parameter ``mem`` of ``-numa node`` is used to assign a part of
+guest RAM to a NUMA node. But when using it, it's impossible to manage specified
+RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
+so guest end-ups with the fake NUMA configuration with suboptiomal performance.
+However since 2014 there is an alternative way to assign RAM to a NUMA node
+using parameter ``memdev``, which does the same as ``mem`` and adds
+means to actualy manage node RAM on the host side. Use parameter ``memdev``
+with *memory-backend-ram* backend as an replacement for parameter ``mem``
+to achieve the same fake NUMA effect or a properly configured
+*memory-backend-file* backend to actually benefit from NUMA configuration.
+In future new machine versions will not accept the option but it will still
+work with old machine types. User can check QAPI schema to see if the legacy
+option is supported by looking at MachineInfo::numa-mem-supported property.
+
+``-numa`` node (without memory specified) (since 4.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Splitting RAM by default between NUMA nodes has the same issues as ``mem``
+parameter described above with the difference that the role of the user plays
+QEMU using implicit generic or board specific splitting rule.
+Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
+it's supported by used machine type) to define mapping explictly instead.
+
+``-mem-path`` fallback to RAM (since 4.1)
+'''''''''''''''''''''''''''''''''''''''''
+
+Currently if guest RAM allocation from file pointed by ``mem-path``
+fails, QEMU falls back to allocating from RAM, which might result
+in unpredictable behavior since the backing file specified by the user
+is ignored. In the future, users will be responsible for making sure
+the backing storage specified with ``-mem-path`` can actually provide
+the guest RAM configured with ``-m`` and QEMU will fail to start up if
+RAM allocation is unsuccessful.
+
+RISC-V ``-bios`` (since 4.1)
+''''''''''''''''''''''''''''
+
+QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
+RISC-V virt machine and sifive_u machine.
+
+QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
+default will change in a future QEMU release, so please prepare now. All users
+of the virt or sifive_u machine must change their command line usage.
+
+QEMU 4.1 has three options, please migrate to one of these three:
+ 1. ``-bios none`` - This is the current default behavior if no -bios option
+      is included. QEMU will not automatically load any firmware. It is up
+      to the user to load all the images they need.
+ 2. ``-bios default`` - In a future QEMU release this will become the default
+      behaviour if no -bios option is specified. This option will load the
+      default OpenSBI firmware automatically. The firmware is included with
+      the QEMU release and no user interaction is required. All a user needs
+      to do is specify the kernel they want to boot with the -kernel option
+ 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
+
+``-tb-size`` option (since 5.0)
+'''''''''''''''''''''''''''''''
+
+QEMU 5.0 introduced an alternative syntax to specify the size of the translation
+block cache, ``-accel tcg,tb-size=``.  The new syntax deprecates the
+previously available ``-tb-size`` option.
+
+``-show-cursor`` option (since 5.0)
+'''''''''''''''''''''''''''''''''''
+
+Use ``-display sdl,show-cursor=on`` or
+ ``-display gtk,show-cursor=on`` instead.
+
+QEMU Machine Protocol (QMP) commands
+------------------------------------
+
+``change`` (since 2.5.0)
+''''''''''''''''''''''''
+
+Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
+
+``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use ``migrate-set-parameters`` instead.
+
+``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
+
+``query-block`` result field ``dirty-bitmaps[i].status`` (since 4.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
+the query-block command is deprecated. Two new boolean fields,
+``recording`` and ``busy`` effectively replace it.
+
+``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
+the query-block command is itself now deprecated. The ``dirty-bitmaps``
+field of the ``BlockDeviceInfo`` struct should be used instead, which is the
+type of the ``inserted`` field in query-block replies, as well as the
+type of array items in query-named-block-nodes.
+
+Since the ``dirty-bitmaps`` field is optionally present in both the old and
+new locations, clients must use introspection to learn where to anticipate
+the field if/when it does appear in command output.
+
+``query-cpus`` (since 2.12.0)
+'''''''''''''''''''''''''''''
+
+The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
+
+``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.
+
+``cpu-add`` (since 4.0)
+'''''''''''''''''''''''
+
+Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
+documentation of ``query-hotpluggable-cpus`` for additional
+details.
+
+``query-events`` (since 4.0)
+''''''''''''''''''''''''''''
+
+The ``query-events`` command has been superseded by the more powerful
+and accurate ``query-qmp-schema`` command.
+
+chardev client socket with ``wait`` option (since 4.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Character devices creating sockets in client mode should not specify
+the 'wait' field, which is only applicable to sockets in server mode
+
+Human Monitor Protocol (HMP) commands
+-------------------------------------
+
+The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (since 3.1)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
+'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
+
+``cpu-add`` (since 4.0)
+'''''''''''''''''''''''
+
+Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
+documentation of ``query-hotpluggable-cpus`` for additional details.
+
+``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (since 4.0.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
+``acl_remove`` commands are deprecated with no replacement. Authorization
+for VNC should be performed using the pluggable QAuthZ objects.
+
+Guest Emulator ISAs
+-------------------
+
+RISC-V ISA privledge specification version 1.09.1 (since 4.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
+QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
+should be used instead of the 1.09.1 version.
+
+System emulator CPUS
+--------------------
+
+RISC-V ISA CPUs (since 4.1)
+'''''''''''''''''''''''''''
+
+The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
+four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
+``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
+option when using the ``rv32`` or ``rv64`` CPUs.
+
+RISC-V ISA CPUs (since 4.1)
+'''''''''''''''''''''''''''
+
+The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
+``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
+via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
+
+System emulator devices
+-----------------------
+
+``ide-drive`` (since 4.2)
+'''''''''''''''''''''''''
+
+The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
+'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
+
+``scsi-disk`` (since 4.2)
+'''''''''''''''''''''''''
+
+The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
+'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
+
+System emulator machines
+------------------------
+
+mips ``r4k`` platform (since 5.0)
+'''''''''''''''''''''''''''''''''
+
+This machine type is very old and unmaintained. Users should use the ``malta``
+machine type instead.
+
+``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.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.
+
+``spike_v1.9.1`` and ``spike_v1.10`` (since 4.1)
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+The version specific Spike machines have been deprecated in favour of the
+generic ``spike`` machine. If you need to specify an older version of the RISC-V
+spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
+
+Device options
+--------------
+
+Emulated device options
+'''''''''''''''''''''''
+
+``-device virtio-blk,scsi=on|off`` (since 5.0.0)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
+and later do not support it because the virtio-scsi device was introduced for
+full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
+
+Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
+alias.
+
+Block device options
+''''''''''''''''''''
+
+``"backing": ""`` (since 2.12.0)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to prevent QEMU from automatically opening an image's backing
+chain, use ``"backing": null`` instead.
+
+``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Options for ``rbd`` should be specified according to its runtime options,
+like other block drivers.  Legacy parsing of keyvalue pair encoded
+filenames is useful to open images with the old format for backing files;
+These image files should be updated to use the current format.
+
+Example of legacy encoding::
+
+  json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
+
+The above, converted to the current supported format::
+
+  json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
+
+Related binaries
+----------------
+
+``qemu-img convert -n -o`` (since 4.2.0)
+''''''''''''''''''''''''''''''''''''''''
+
+All options specified in ``-o`` are image creation options, so
+they have no effect when used with ``-n`` to skip image creation.
+Silently ignored options can be confusing, so this combination of
+options will be made an error in future versions.
+
+Backwards compatibility
+-----------------------
+
+Runnability guarantee of CPU models (since 4.1.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''
+
+Previous versions of QEMU never changed existing CPU models in
+ways that introduced additional host software or hardware
+requirements to the VM.  This allowed management software to
+safely change the machine type of an existing VM without
+introducing new requirements ("runnability guarantee").  This
+prevented CPU models from being updated to include CPU
+vulnerability mitigations, leaving guests vulnerable in the
+default configuration.
+
+The CPU model runnability guarantee won't apply anymore to
+existing CPU models.  Management software that needs runnability
+guarantees must resolve the CPU model aliases using te
+``alias-of`` field returned by the ``query-cpu-definitions`` QMP
+command.
+
+While those guarantees are kept, the return value of
+``query-cpu-definitions`` will have existing CPU model aliases
+point to a version that doesn't break runnability guarantees
+(specifically, version 1 of those CPU models).  In future QEMU
+versions, aliases will point to newer CPU model versions
+depending on the machine type, so management software must
+resolve CPU model aliases before starting a virtual machine.
+
+
+Recently removed features
+=========================
+
+What follows is a record of recently removed, formerly deprecated
+features that serves as a record for users who have encountered
+trouble after a recent upgrade.
+
+QEMU Machine Protocol (QMP) commands
+------------------------------------
+
+``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+The "autoload" parameter has been ignored since 2.12.0. All bitmaps
+are automatically loaded from qcow2 images.
+
+Related binaries
+----------------
+
+``qemu-nbd --partition`` (removed in 5.0.0)
+'''''''''''''''''''''''''''''''''''''''''''
+
+The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
+could only handle MBR partitions, and never correctly handled logical
+partitions beyond partition 5.  Exporting a partition can still be
+done by utilizing the ``--image-opts`` option with a raw blockdev
+using the ``offset`` and ``size`` parameters layered on top of
+any other existing blockdev. For example, if partition 1 is 100MiB
+long starting at 1MiB, the old command::
+
+  qemu-nbd -t -P 1 -f qcow2 file.qcow2
+
+can be rewritten as::
+
+  qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
diff --git a/docs/system/device-url-syntax.rst.inc b/docs/system/device-url-syntax.rst.inc
new file mode 100644
index 0000000000..88d7a372a7
--- /dev/null
+++ b/docs/system/device-url-syntax.rst.inc
@@ -0,0 +1,228 @@
+
+In addition to using normal file images for the emulated storage
+devices, QEMU can also use networked resources such as iSCSI devices.
+These are specified using a special URL syntax.
+
+``iSCSI``
+   iSCSI support allows QEMU to access iSCSI resources directly and use
+   as images for the guest storage. Both disk and cdrom images are
+   supported.
+
+   Syntax for specifying iSCSI LUNs is
+   "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
+
+   By default qemu will use the iSCSI initiator-name
+   'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
+   the command line or a configuration file.
+
+   Since version Qemu 2.4 it is possible to specify a iSCSI request
+   timeout to detect stalled requests and force a reestablishment of the
+   session. The timeout is specified in seconds. The default is 0 which
+   means no timeout. Libiscsi 1.15.0 or greater is required for this
+   feature.
+
+   Example (without authentication):
+
+   .. parsed-literal::
+
+      |qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
+                       -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
+                       -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
+
+   Example (CHAP username/password via URL):
+
+   .. parsed-literal::
+
+      |qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
+
+   Example (CHAP username/password via environment variables):
+
+   .. parsed-literal::
+
+      LIBISCSI_CHAP_USERNAME="user" \
+      LIBISCSI_CHAP_PASSWORD="password" \
+      |qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
+
+``NBD``
+   QEMU supports NBD (Network Block Devices) both using TCP protocol as
+   well as Unix Domain Sockets. With TCP, the default port is 10809.
+
+   Syntax for specifying a NBD device using TCP, in preferred URI form:
+   "nbd://<server-ip>[:<port>]/[<export>]"
+
+   Syntax for specifying a NBD device using Unix Domain Sockets;
+   remember that '?' is a shell glob character and may need quoting:
+   "nbd+unix:///[<export>]?socket=<domain-socket>"
+
+   Older syntax that is also recognized:
+   "nbd:<server-ip>:<port>[:exportname=<export>]"
+
+   Syntax for specifying a NBD device using Unix Domain Sockets
+   "nbd:unix:<domain-socket>[:exportname=<export>]"
+
+   Example for TCP
+
+   .. parsed-literal::
+
+      |qemu_system| --drive file=nbd:192.0.2.1:30000
+
+   Example for Unix Domain Sockets
+
+   .. parsed-literal::
+
+      |qemu_system| --drive file=nbd:unix:/tmp/nbd-socket
+
+``SSH``
+   QEMU supports SSH (Secure Shell) access to remote disks.
+
+   Examples:
+
+   .. parsed-literal::
+
+      |qemu_system| -drive file=ssh://user@host/path/to/disk.img
+      |qemu_system| -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
+
+   Currently authentication must be done using ssh-agent. Other
+   authentication methods may be supported in future.
+
+``Sheepdog``
+   Sheepdog is a distributed storage system for QEMU. QEMU supports
+   using either local sheepdog devices or remote networked devices.
+
+   Syntax for specifying a sheepdog device
+
+   ::
+
+      sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
+
+   Example
+
+   .. parsed-literal::
+
+      |qemu_system| --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
+
+   See also https://sheepdog.github.io/sheepdog/.
+
+``GlusterFS``
+   GlusterFS is a user space distributed file system. QEMU supports the
+   use of GlusterFS volumes for hosting VM disk images using TCP, Unix
+   Domain Sockets and RDMA transport protocols.
+
+   Syntax for specifying a VM disk image on GlusterFS volume is
+
+   .. parsed-literal::
+
+      URI:
+      gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
+
+      JSON:
+      'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
+                                       "server":[{"type":"tcp","host":"...","port":"..."},
+                                                 {"type":"unix","socket":"..."}]}}'
+
+   Example
+
+   .. parsed-literal::
+
+      URI:
+      |qemu_system| --drive file=gluster://192.0.2.1/testvol/a.img,
+                                     file.debug=9,file.logfile=/var/log/qemu-gluster.log
+
+      JSON:
+      |qemu_system| '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| -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
+
+   See also http://www.gluster.org.
+
+``HTTP/HTTPS/FTP/FTPS``
+   QEMU supports read-only access to files accessed over http(s) and
+   ftp(s).
+
+   Syntax using a single filename:
+
+   ::
+
+      <protocol>://[<username>[:<password>]@]<host>/<path>
+
+   where:
+
+   ``protocol``
+      'http', 'https', 'ftp', or 'ftps'.
+
+   ``username``
+      Optional username for authentication to the remote server.
+
+   ``password``
+      Optional password for authentication to the remote server.
+
+   ``host``
+      Address of the remote server.
+
+   ``path``
+      Path on the remote server, including any query string.
+
+   The following options are also supported:
+
+   ``url``
+      The full URL when passing options to the driver explicitly.
+
+   ``readahead``
+      The amount of data to read ahead with each range request to the
+      remote server. This value may optionally have the suffix 'T', 'G',
+      'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be
+      assumed to be in bytes. The value must be a multiple of 512 bytes.
+      It defaults to 256k.
+
+   ``sslverify``
+      Whether to verify the remote server's certificate when connecting
+      over SSL. It can have the value 'on' or 'off'. It defaults to
+      'on'.
+
+   ``cookie``
+      Send this cookie (it can also be a list of cookies separated by
+      ';') with each outgoing request. Only supported when using
+      protocols such as HTTP which support cookies, otherwise ignored.
+
+   ``timeout``
+      Set the timeout in seconds of the CURL connection. This timeout is
+      the time that CURL waits for a response from the remote server to
+      get the size of the image to be downloaded. If not set, the
+      default timeout of 5 seconds is used.
+
+   Note that when passing options to qemu explicitly, ``driver`` is the
+   value of <protocol>.
+
+   Example: boot from a remote Fedora 20 live ISO image
+
+   .. parsed-literal::
+
+      |qemu_system_x86| --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
+
+      |qemu_system_x86| --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
+
+   Example: boot from a remote Fedora 20 cloud image using a local
+   overlay for writes, copy-on-read, and a readahead of 64k
+
+   .. parsed-literal::
+
+      qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
+
+      |qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
+
+   Example: boot from an image stored on a VMware vSphere server with a
+   self-signed certificate using a local overlay for writes, a readahead
+   of 64k and a timeout of 10 seconds.
+
+   .. parsed-literal::
+
+      qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"https",, "file.url":"https://user:password@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10}' /tmp/test.qcow2
+
+      |qemu_system_x86| -drive file=/tmp/test.qcow2
diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst
new file mode 100644
index 0000000000..639f814b32
--- /dev/null
+++ b/docs/system/gdb.rst
@@ -0,0 +1,81 @@
+.. _gdb_005fusage:
+
+GDB usage
+---------
+
+QEMU has a primitive support to work with gdb, so that you can do
+'Ctrl-C' while the virtual machine is running and inspect its state.
+
+In order to use gdb, launch QEMU with the '-s' option. It will wait for
+a gdb connection:
+
+.. parsed-literal::
+
+   |qemu_system| -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
+   Connected to host network interface: tun0
+   Waiting gdb connection on port 1234
+
+Then launch gdb on the 'vmlinux' executable::
+
+   > gdb vmlinux
+
+In gdb, connect to QEMU::
+
+   (gdb) target remote localhost:1234
+
+Then you can use gdb normally. For example, type 'c' to launch the
+kernel::
+
+   (gdb) c
+
+Here are some useful tips in order to use gdb on system code:
+
+1. Use ``info reg`` to display all the CPU registers.
+
+2. Use ``x/10i $eip`` to display the code at the PC position.
+
+3. Use ``set architecture i8086`` to dump 16 bit code. Then use
+   ``x/10i $cs*16+$eip`` to dump the code at the PC position.
+
+Advanced debugging options:
+
+The default single stepping behavior is step with the IRQs and timer
+service routines off. It is set this way because when gdb executes a
+single step it expects to advance beyond the current instruction. With
+the IRQs and timer service routines on, a single step might jump into
+the one of the interrupt or exception vectors instead of executing the
+current instruction. This means you may hit the same breakpoint a number
+of times before executing the instruction gdb wants to have executed.
+Because there are rare circumstances where you want to single step into
+an interrupt vector the behavior can be controlled from GDB. There are
+three commands you can query and set the single step behavior:
+
+``maintenance packet qqemu.sstepbits``
+   This will display the MASK bits used to control the single stepping
+   IE:
+
+   ::
+
+      (gdb) maintenance packet qqemu.sstepbits
+      sending: "qqemu.sstepbits"
+      received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
+
+``maintenance packet qqemu.sstep``
+   This will display the current value of the mask used when single
+   stepping IE:
+
+   ::
+
+      (gdb) maintenance packet qqemu.sstep
+      sending: "qqemu.sstep"
+      received: "0x7"
+
+``maintenance packet Qqemu.sstep=HEX_VALUE``
+   This will change the single step mask, so if wanted to enable IRQs on
+   the single step, but not timers, you would use:
+
+   ::
+
+      (gdb) maintenance packet Qqemu.sstep=0x5
+      sending: "qemu.sstep=0x5"
+      received: "OK"
diff --git a/docs/system/images.rst b/docs/system/images.rst
new file mode 100644
index 0000000000..ff26bf9587
--- /dev/null
+++ b/docs/system/images.rst
@@ -0,0 +1,85 @@
+.. _disk_005fimages:
+
+Disk Images
+-----------
+
+QEMU supports many disk image formats, including growable disk images
+(their size increase as non empty sectors are written), compressed and
+encrypted disk images.
+
+.. _disk_005fimages_005fquickstart:
+
+Quick start for disk image creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can create a disk image with the command::
+
+   qemu-img create myimage.img mysize
+
+where myimage.img is the disk image filename and mysize is its size in
+kilobytes. You can add an ``M`` suffix to give the size in megabytes and
+a ``G`` suffix for gigabytes.
+
+See the qemu-img invocation documentation for more information.
+
+.. _disk_005fimages_005fsnapshot_005fmode:
+
+Snapshot mode
+~~~~~~~~~~~~~
+
+If you use the option ``-snapshot``, all disk images are considered as
+read only. When sectors in written, they are written in a temporary file
+created in ``/tmp``. You can however force the write back to the raw
+disk images by using the ``commit`` monitor command (or C-a s in the
+serial console).
+
+.. _vm_005fsnapshots:
+
+VM snapshots
+~~~~~~~~~~~~
+
+VM snapshots are snapshots of the complete virtual machine including CPU
+state, RAM, device state and the content of all the writable disks. In
+order to use VM snapshots, you must have at least one non removable and
+writable block device using the ``qcow2`` disk image format. Normally
+this device is the first virtual hard drive.
+
+Use the monitor command ``savevm`` to create a new VM snapshot or
+replace an existing one. A human readable name can be assigned to each
+snapshot in addition to its numerical ID.
+
+Use ``loadvm`` to restore a VM snapshot and ``delvm`` to remove a VM
+snapshot. ``info snapshots`` lists the available snapshots with their
+associated information::
+
+   (qemu) info snapshots
+   Snapshot devices: hda
+   Snapshot list (from hda):
+   ID        TAG                 VM SIZE                DATE       VM CLOCK
+   1         start                   41M 2006-08-06 12:38:02   00:00:14.954
+   2                                 40M 2006-08-06 12:43:29   00:00:18.633
+   3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
+
+A VM snapshot is made of a VM state info (its size is shown in
+``info snapshots``) and a snapshot of every writable disk image. The VM
+state info is stored in the first ``qcow2`` non removable and writable
+block device. The disk image snapshots are stored in every disk image.
+The size of a snapshot in a disk image is difficult to evaluate and is
+not shown by ``info snapshots`` because the associated disk sectors are
+shared among all the snapshots to save disk space (otherwise each
+snapshot would need a full copy of all the disk images).
+
+When using the (unrelated) ``-snapshot`` option
+(:ref:`disk_005fimages_005fsnapshot_005fmode`),
+you can always make VM snapshots, but they are deleted as soon as you
+exit QEMU.
+
+VM snapshots currently have the following known limitations:
+
+-  They cannot cope with removable devices if they are removed or
+   inserted after a snapshot is done.
+
+-  A few device drivers still have incomplete snapshot support so their
+   state is not saved or restored properly (in particular USB).
+
+.. include:: qemu-block-drivers.rst.inc
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 1a4b2c82ac..6e5f20fa13 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -12,7 +12,25 @@ or Hypervisor.Framework.
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
-   qemu-block-drivers
+   quickstart
+   invocation
+   keys
+   mux-chardev
+   monitor
+   images
+   net
+   usb
+   ivshmem
+   linuxboot
+   vnc-security
+   tls
+   gdb
+   managed-startup
+   targets
+   security
    vfio-ap
+   deprecated
+   build-platforms
+   license
diff --git a/docs/system/invocation.rst b/docs/system/invocation.rst
new file mode 100644
index 0000000000..4ba38fc23d
--- /dev/null
+++ b/docs/system/invocation.rst
@@ -0,0 +1,18 @@
+.. _sec_005finvocation:
+
+Invocation
+----------
+
+.. parsed-literal::
+
+   |qemu_system| [options] [disk_image]
+
+disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
+not need a disk image.
+
+.. hxtool-doc:: qemu-options.hx
+
+Device URL Syntax
+~~~~~~~~~~~~~~~~~
+
+.. include:: device-url-syntax.rst.inc
diff --git a/docs/system/ivshmem.rst b/docs/system/ivshmem.rst
new file mode 100644
index 0000000000..b03a48afa3
--- /dev/null
+++ b/docs/system/ivshmem.rst
@@ -0,0 +1,64 @@
+.. _pcsys_005fivshmem:
+
+Inter-VM Shared Memory device
+-----------------------------
+
+On Linux hosts, a shared memory device is available. The basic syntax
+is:
+
+.. parsed-literal::
+
+   |qemu_system_x86| -device ivshmem-plain,memdev=hostmem
+
+where hostmem names a host memory backend. For a POSIX shared memory
+backend, use something like
+
+::
+
+   -object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=hostmem
+
+If desired, interrupts can be sent between guest VMs accessing the same
+shared memory region. Interrupt support requires using a shared memory
+server and using a chardev socket to connect to it. The code for the
+shared memory server is qemu.git/contrib/ivshmem-server. An example
+syntax when using the shared memory server is:
+
+.. parsed-literal::
+
+   # First start the ivshmem server once and for all
+   ivshmem-server -p pidfile -S path -m shm-name -l shm-size -n vectors
+
+   # Then start your qemu instances with matching arguments
+   |qemu_system_x86| -device ivshmem-doorbell,vectors=vectors,chardev=id
+                    -chardev socket,path=path,id=id
+
+When using the server, the guest will be assigned a VM ID (>=0) that
+allows guests using the same server to communicate via interrupts.
+Guests can read their VM ID from a device register (see
+ivshmem-spec.txt).
+
+Migration with ivshmem
+~~~~~~~~~~~~~~~~~~~~~~
+
+With device property ``master=on``, the guest will copy the shared
+memory on migration to the destination host. With ``master=off``, the
+guest will not be able to migrate with the device attached. In the
+latter case, the device should be detached and then reattached after
+migration using the PCI hotplug support.
+
+At most one of the devices sharing the same memory can be master. The
+master must complete migration before you plug back the other devices.
+
+ivshmem and hugepages
+~~~~~~~~~~~~~~~~~~~~~
+
+Instead of specifying the <shm size> using POSIX shm, you may specify a
+memory backend that has hugepage support:
+
+.. parsed-literal::
+
+   |qemu_system_x86| -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
+                    -device ivshmem-plain,memdev=mb1
+
+ivshmem-server also supports hugepages mount points with the ``-m``
+memory path argument.
diff --git a/docs/system/keys.rst b/docs/system/keys.rst
new file mode 100644
index 0000000000..e596ae6c4e
--- /dev/null
+++ b/docs/system/keys.rst
@@ -0,0 +1,6 @@
+.. _pcsys_005fkeys:
+
+Keys in the graphical frontends
+-------------------------------
+
+.. include:: keys.rst.inc
diff --git a/docs/system/keys.rst.inc b/docs/system/keys.rst.inc
new file mode 100644
index 0000000000..bd9b8e5f6f
--- /dev/null
+++ b/docs/system/keys.rst.inc
@@ -0,0 +1,35 @@
+During the graphical emulation, you can use special key combinations to
+change modes. The default key mappings are shown below, but if you use
+``-alt-grab`` then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt)
+and if you use ``-ctrl-grab`` then the modifier is the right Ctrl key
+(instead of Ctrl-Alt):
+
+Ctrl-Alt-f
+   Toggle full screen
+
+Ctrl-Alt-+
+   Enlarge the screen
+
+Ctrl-Alt\--
+   Shrink the screen
+
+Ctrl-Alt-u
+   Restore the screen's un-scaled dimensions
+
+Ctrl-Alt-n
+   Switch to virtual console 'n'. Standard console mappings are:
+
+   *1*
+      Target system display
+
+   *2*
+      Monitor
+
+   *3*
+      Serial port
+
+Ctrl-Alt
+   Toggle mouse and keyboard grab.
+
+In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp and
+Ctrl-PageDown to move in the back log.
diff --git a/docs/system/license.rst b/docs/system/license.rst
new file mode 100644
index 0000000000..cde3d2d25d
--- /dev/null
+++ b/docs/system/license.rst
@@ -0,0 +1,11 @@
+.. _License:
+
+License
+=======
+
+QEMU is a trademark of Fabrice Bellard.
+
+QEMU is released under the `GNU General Public
+License <https://www.gnu.org/licenses/gpl-2.0.txt>`__, version 2. Parts
+of QEMU have specific licenses, see file
+`LICENSE <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE>`__.
diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
new file mode 100644
index 0000000000..228650abc5
--- /dev/null
+++ b/docs/system/linuxboot.rst
@@ -0,0 +1,30 @@
+.. _direct_005flinux_005fboot:
+
+Direct Linux Boot
+-----------------
+
+This section explains how to launch a Linux kernel inside QEMU without
+having to make a full bootable image. It is very useful for fast Linux
+kernel testing.
+
+The syntax is:
+
+.. parsed-literal::
+
+   |qemu_system| -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
+
+Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
+give the kernel command line arguments. The ``-initrd`` option can be
+used to provide an INITRD image.
+
+If you do not need graphical output, you can disable it and redirect the
+virtual serial port and the QEMU monitor to the console with the
+``-nographic`` option. The typical command line is:
+
+.. parsed-literal::
+
+   |qemu_system| -kernel bzImage -hda rootdisk.img \
+                    -append "root=/dev/hda console=ttyS0" -nographic
+
+Use Ctrl-a c to switch between the serial console and the monitor (see
+:ref:`pcsys_005fkeys`).
diff --git a/docs/system/managed-startup.rst b/docs/system/managed-startup.rst
new file mode 100644
index 0000000000..9bcf98ea79
--- /dev/null
+++ b/docs/system/managed-startup.rst
@@ -0,0 +1,35 @@
+Managed start up options
+========================
+
+In system mode emulation, it's possible to create a VM in a paused
+state using the ``-S`` command line option. In this state the machine
+is completely initialized according to command line options and ready
+to execute VM code but VCPU threads are not executing any code. The VM
+state in this paused state depends on the way QEMU was started. It
+could be in:
+
+- initial state (after reset/power on state)
+- with direct kernel loading, the initial state could be amended to execute
+  code loaded by QEMU in the VM's RAM and with incoming migration
+- with incoming migration, initial state will be amended with the migrated
+  machine state after migration completes
+
+This paused state is typically used by users to query machine state and/or
+additionally configure the machine (by hotplugging devices) in runtime before
+allowing VM code to run.
+
+However, at the ``-S`` pause point, it's impossible to configure options
+that affect initial VM creation (like: ``-smp``/``-m``/``-numa`` ...) or
+cold plug devices. The experimental ``--preconfig`` command line option
+allows pausing QEMU before the initial VM creation, in a "preconfig" state,
+where additional queries and configuration can be performed via QMP
+before moving on to the resulting configuration startup. In the
+preconfig state, QEMU only allows a limited set of commands over the
+QMP monitor, where the commands do not depend on an initialized
+machine, including but not limited to:
+
+- ``qmp_capabilities``
+- ``query-qmp-schema``
+- ``query-commands``
+- ``query-status``
+- ``x-exit-preconfig``
diff --git a/docs/system/monitor.rst b/docs/system/monitor.rst
new file mode 100644
index 0000000000..0bcd5da216
--- /dev/null
+++ b/docs/system/monitor.rst
@@ -0,0 +1,31 @@
+.. _pcsys_005fmonitor:
+
+QEMU Monitor
+------------
+
+The QEMU monitor is used to give complex commands to the QEMU emulator.
+You can use it to:
+
+-  Remove or insert removable media images (such as CD-ROM or
+   floppies).
+
+-  Freeze/unfreeze the Virtual Machine (VM) and save or restore its
+   state from a disk file.
+
+-  Inspect the VM state without an external debugger.
+
+Commands
+~~~~~~~~
+
+The following commands are available:
+
+.. hxtool-doc:: hmp-commands.hx
+
+.. hxtool-doc:: hmp-commands-info.hx
+
+Integer expressions
+~~~~~~~~~~~~~~~~~~~
+
+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 *$*.
diff --git a/docs/system/mux-chardev.rst b/docs/system/mux-chardev.rst
new file mode 100644
index 0000000000..413a6b3446
--- /dev/null
+++ b/docs/system/mux-chardev.rst
@@ -0,0 +1,6 @@
+.. _mux_005fkeys:
+
+Keys in the character backend multiplexer
+-----------------------------------------
+
+.. include:: mux-chardev.rst.inc
diff --git a/docs/system/mux-chardev.rst.inc b/docs/system/mux-chardev.rst.inc
new file mode 100644
index 0000000000..84ea12cbf5
--- /dev/null
+++ b/docs/system/mux-chardev.rst.inc
@@ -0,0 +1,27 @@
+During emulation, if you are using a character backend multiplexer
+(which is the default if you are using ``-nographic``) then several
+commands are available via an escape sequence. These key sequences all
+start with an escape character, which is Ctrl-a by default, but can be
+changed with ``-echr``. The list below assumes you're using the default.
+
+Ctrl-a h
+   Print this help
+
+Ctrl-a x
+   Exit emulator
+
+Ctrl-a s
+   Save disk data back to file (if -snapshot)
+
+Ctrl-a t
+   Toggle console timestamps
+
+Ctrl-a b
+   Send break (magic sysrq in Linux)
+
+Ctrl-a c
+   Rotate between the frontends connected to the multiplexer (usually
+   this switches between the monitor and the console)
+
+Ctrl-a Ctrl-a
+   Send the escape character to the frontend
diff --git a/docs/system/net.rst b/docs/system/net.rst
new file mode 100644
index 0000000000..4b2640c448
--- /dev/null
+++ b/docs/system/net.rst
@@ -0,0 +1,100 @@
+.. _pcsys_005fnetwork:
+
+Network emulation
+-----------------
+
+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).
+
+Using TAP network interfaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the standard way to connect QEMU to a real network. QEMU adds a
+virtual network device on your host (called ``tapN``), and you can then
+configure it as if it was a real ethernet card.
+
+Linux host
+^^^^^^^^^^
+
+As an example, you can download the ``linux-test-xxx.tar.gz`` archive
+and copy the script ``qemu-ifup`` in ``/etc`` and configure properly
+``sudo`` so that the command ``ifconfig`` contained in ``qemu-ifup`` can
+be executed as root. You must verify that your host kernel supports the
+TAP network interfaces: the device ``/dev/net/tun`` must be present.
+
+See :ref:`sec_005finvocation` to have examples of command
+lines using the TAP network interfaces.
+
+Windows host
+^^^^^^^^^^^^
+
+There is a virtual ethernet driver for Windows 2000/XP systems, called
+TAP-Win32. But it is not included in standard QEMU for Windows, so you
+will need to get it separately. It is part of OpenVPN package, so
+download OpenVPN from : https://openvpn.net/.
+
+Using the user mode network stack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By using the option ``-net user`` (default configuration if no ``-net``
+option is specified), QEMU uses a completely user mode network stack
+(you don't need root privilege to use the virtual network). The virtual
+network configuration is the following::
+
+        guest (10.0.2.15)  <------>  Firewall/DHCP server <-----> Internet
+                              |          (10.0.2.2)
+                              |
+                              ---->  DNS server (10.0.2.3)
+                              |
+                              ---->  SMB server (10.0.2.4)
+
+The QEMU VM behaves as if it was behind a firewall which blocks all
+incoming connections. You can use a DHCP client to automatically
+configure the network in the QEMU VM. The DHCP server assign addresses
+to the hosts starting from 10.0.2.15.
+
+In order to check that the user mode network is working, you can ping
+the address 10.0.2.2 and verify that you got an address in the range
+10.0.2.x from the QEMU virtual DHCP server.
+
+Note that ICMP traffic in general does not work with user mode
+networking. ``ping``, aka. ICMP echo, to the local router (10.0.2.2)
+shall work, however. If you're using QEMU on Linux >= 3.0, it can use
+unprivileged ICMP ping sockets to allow ``ping`` to the Internet. The
+host admin has to set the ping_group_range in order to grant access to
+those sockets. To allow ping for GID 100 (usually users group)::
+
+   echo 100 100 > /proc/sys/net/ipv4/ping_group_range
+
+When using the built-in TFTP server, the router is also the TFTP server.
+
+When using the ``'-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.
+
+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 ``-netdev
+hubport`` or ``-nic hubport`` options. The legacy ``-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 ``-net nic,netdev=xxx``
+here.
+
+Connecting emulated networks between QEMU instances
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using the ``-netdev socket`` (or ``-nic socket`` or ``-net socket``)
+option, it is possible to create emulated networks that span several
+QEMU instances. See the description of the ``-netdev socket`` option in
+:ref:`sec_005finvocation` to have a basic
+example.
diff --git a/docs/system/qemu-block-drivers.rst b/docs/system/qemu-block-drivers.rst
index 388adbefbf..bd99d4fa8e 100644
--- a/docs/system/qemu-block-drivers.rst
+++ b/docs/system/qemu-block-drivers.rst
@@ -1,985 +1,20 @@
+:orphan:
+
 QEMU block drivers reference
 ============================
 
-.. |qemu_system| replace:: qemu-system-x86_64
-
-..
-   We put the 'Synopsis' and 'See also' sections into the manpage, but not
-   the HTML. This makes the HTML docs read better and means the ToC in
-   the index has a more useful set of entries. Ideally, the section
-   headings 'Disk image file formats' would be top-level headings for
-   the HTML, but sub-headings of the conventional manpage 'Description'
-   header for the manpage. Unfortunately, due to deficiencies in
-   the Sphinx 'only' directive, this isn't possible: they must be headers
-   at the same level as 'Synopsis' and 'See also', otherwise Sphinx's
-   identification of which header underline style is which gets confused.
-
-.. only:: man
-
-  Synopsis
-  --------
-
-  QEMU block driver reference manual
-
-Disk image file formats
------------------------
-
-QEMU supports many image file formats that can be used with VMs as well as with
-any of the tools (like ``qemu-img``). This includes the preferred formats
-raw and qcow2 as well as formats that are supported for compatibility with
-older QEMU versions or other hypervisors.
-
-Depending on the image format, different options can be passed to
-``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option.
-This section describes each format and the options that are supported for it.
-
-.. program:: image-formats
-.. option:: raw
-
-  Raw disk image format. This format has the advantage of
-  being simple and easily exportable to all other emulators. If your
-  file system supports *holes* (for example in ext2 or ext3 on
-  Linux or NTFS on Windows), then only the written sectors will reserve
-  space. Use ``qemu-img info`` to know the real size used by the
-  image or ``ls -ls`` on Unix/Linux.
-
-  Supported options:
-
-  .. program:: raw
-  .. option:: preallocation
-
-    Preallocation mode (allowed values: ``off``, ``falloc``,
-    ``full``). ``falloc`` mode preallocates space for image by
-    calling ``posix_fallocate()``. ``full`` mode preallocates space
-    for image by writing data to underlying storage. This data may or
-    may not be zero, depending on the storage location.
-
-.. program:: image-formats
-.. option:: qcow2
-
-  QEMU image format, the most versatile format. Use it to have smaller
-  images (useful if your filesystem does not supports holes, for example
-  on Windows), zlib based compression and support of multiple VM
-  snapshots.
-
-  Supported options:
-
-  .. program:: qcow2
-  .. option:: compat
-
-    Determines the qcow2 version to use. ``compat=0.10`` uses the
-    traditional image format that can be read by any QEMU since 0.10.
-    ``compat=1.1`` enables image format extensions that only QEMU 1.1 and
-    newer understand (this is the default). Amongst others, this includes
-    zero clusters, which allow efficient copy-on-read for sparse images.
-
-  .. option:: backing_file
-
-    File name of a base image (see ``create`` subcommand)
-
-  .. option:: backing_fmt
-
-    Image format of the base image
-
-  .. option:: encryption
-
-    This option is deprecated and equivalent to ``encrypt.format=aes``
-
-  .. option:: encrypt.format
-
-    If this is set to ``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 ``encrypt.key-secret``
-    parameter. LUKS encryption parameters can be tuned with the other
-    ``encrypt.*`` parameters.
-
-    If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
-    The encryption key is given by the ``encrypt.key-secret`` parameter.
-    This encryption format is considered to be flawed by modern cryptography
-    standards, suffering from a number of design problems:
-
-    - The AES-CBC cipher is used with predictable initialization vectors based
-      on the sector number. This makes it vulnerable to chosen plaintext attacks
-      which can reveal the existence of encrypted data.
-    - The user passphrase is directly used as the encryption key. A poorly
-      chosen or short passphrase will compromise the security of the encryption.
-    - In the event of the passphrase being compromised there is no way to
-      change the passphrase to protect data in any qcow images. The files must
-      be cloned, using a different encryption passphrase in the new file. The
-      original file must then be securely erased using a program like shred,
-      though even this is ineffective with many modern storage technologies.
-
-    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 ``luks`` format
-    should be used instead.
-
-  .. option:: encrypt.key-secret
-
-    Provides the ID of a ``secret`` object that contains the passphrase
-    (``encrypt.format=luks``) or encryption key (``encrypt.format=aes``).
-
-  .. option:: encrypt.cipher-alg
-
-    Name of the cipher algorithm and key length. Currently defaults
-    to ``aes-256``. Only used when ``encrypt.format=luks``.
-
-  .. option:: encrypt.cipher-mode
-
-    Name of the encryption mode to use. Currently defaults to ``xts``.
-    Only used when ``encrypt.format=luks``.
-
-  .. option:: encrypt.ivgen-alg
-
-    Name of the initialization vector generator algorithm. Currently defaults
-    to ``plain64``. Only used when ``encrypt.format=luks``.
-
-  .. option:: encrypt.ivgen-hash-alg
-
-    Name of the hash algorithm to use with the initialization vector generator
-    (if required). Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
-
-  .. option:: encrypt.hash-alg
-
-    Name of the hash algorithm to use for PBKDF algorithm
-    Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
-
-  .. option:: encrypt.iter-time
-
-    Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
-    Defaults to ``2000``. Only used when ``encrypt.format=luks``.
-
-  .. option:: cluster_size
-
-    Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
-    sizes can improve the image file size whereas larger cluster sizes generally
-    provide better performance.
-
-  .. option:: preallocation
-
-    Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``,
-    ``full``). An image with preallocated metadata is initially larger but can
-    improve performance when the image needs to grow. ``falloc`` and ``full``
-    preallocations are like the same options of ``raw`` format, but sets up
-    metadata also.
-
-  .. option:: lazy_refcounts
-
-    If this option is set to ``on``, reference count updates are postponed with
-    the goal of avoiding metadata I/O and improving performance. This is
-    particularly interesting with :option:`cache=writethrough` which doesn't batch
-    metadata updates. The tradeoff is that after a host crash, the reference count
-    tables must be rebuilt, i.e. on the next open an (automatic) ``qemu-img
-    check -r all`` is required, which may take some time.
-
-    This option can only be enabled if ``compat=1.1`` is specified.
-
-  .. option:: nocow
-
-    If this option is set to ``on``, it will turn off COW of the file. It's only
-    valid on btrfs, no effect on other file systems.
-
-    Btrfs has low performance when hosting a VM image file, even more
-    when the guest on the VM also using btrfs as file system. Turning off
-    COW is a way to mitigate this bad performance. Generally there are two
-    ways to turn off COW on btrfs:
-
-    - Disable it by mounting with nodatacow, then all newly created files
-      will be NOCOW.
-    - For an empty file, add the NOCOW file attribute. That's what this
-      option does.
-
-    Note: this option is only valid to new or empty files. If there is
-    an existing file which is COW and has data blocks already, it couldn't
-    be changed to NOCOW by setting ``nocow=on``. One can issue ``lsattr
-    filename`` to check if the NOCOW flag is set or not (Capital 'C' is
-    NOCOW flag).
-
-.. program:: image-formats
-.. option:: qed
-
-   Old QEMU image format with support for backing files and compact image files
-   (when your filesystem or transport medium does not support holes).
-
-   When converting QED images to qcow2, you might want to consider using the
-   ``lazy_refcounts=on`` option to get a more QED-like behaviour.
-
-   Supported options:
-
-   .. program:: qed
-   .. option:: backing_file
-
-      File name of a base image (see ``create`` subcommand).
-
-   .. option:: backing_fmt
-
-     Image file format of backing file (optional).  Useful if the format cannot be
-     autodetected because it has no header, like some vhd/vpc files.
-
-   .. option:: cluster_size
-
-     Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
-     cluster sizes can improve the image file size whereas larger cluster sizes
-     generally provide better performance.
-
-   .. option:: table_size
-
-     Changes the number of clusters per L1/L2 table (must be
-     power-of-2 between 1 and 16).  There is normally no need to
-     change this value but this option can between used for
-     performance benchmarking.
-
-.. program:: image-formats
-.. option:: qcow
-
-  Old QEMU image format with support for backing files, compact image files,
-  encryption and compression.
-
-  Supported options:
-
-   .. program:: qcow
-   .. option:: backing_file
-
-     File name of a base image (see ``create`` subcommand)
-
-   .. option:: encryption
-
-     This option is deprecated and equivalent to ``encrypt.format=aes``
-
-   .. option:: encrypt.format
-
-     If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
-     The encryption key is given by the ``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 ``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 ``qcow2`` format
-     instead with ``encrypt.format=luks``.
-
-   .. option:: encrypt.key-secret
-
-     Provides the ID of a ``secret`` object that contains the encryption
-     key (``encrypt.format=aes``).
-
-.. program:: image-formats
-.. option:: luks
-
-  LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
-
-  Supported options:
-
-  .. program:: luks
-  .. option:: key-secret
-
-    Provides the ID of a ``secret`` object that contains the passphrase.
-
-  .. option:: cipher-alg
-
-    Name of the cipher algorithm and key length. Currently defaults
-    to ``aes-256``.
-
-  .. option:: cipher-mode
-
-    Name of the encryption mode to use. Currently defaults to ``xts``.
-
-  .. option:: ivgen-alg
-
-    Name of the initialization vector generator algorithm. Currently defaults
-    to ``plain64``.
-
-  .. option:: ivgen-hash-alg
-
-    Name of the hash algorithm to use with the initialization vector generator
-    (if required). Defaults to ``sha256``.
-
-  .. option:: hash-alg
-
-    Name of the hash algorithm to use for PBKDF algorithm
-    Defaults to ``sha256``.
-
-  .. option:: iter-time
-
-    Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
-    Defaults to ``2000``.
-
-.. program:: image-formats
-.. option:: vdi
-
-  VirtualBox 1.1 compatible image format.
-
-  Supported options:
-
-  .. program:: vdi
-  .. option:: static
-
-    If this option is set to ``on``, the image is created with metadata
-    preallocation.
-
-.. program:: image-formats
-.. option:: vmdk
-
-  VMware 3 and 4 compatible image format.
-
-  Supported options:
-
-  .. program: vmdk
-  .. option:: backing_file
-
-    File name of a base image (see ``create`` subcommand).
-
-  .. option:: compat6
-
-    Create a VMDK version 6 image (instead of version 4)
-
-  .. option:: hwversion
-
-    Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
-    if hwversion is specified.
-
-  .. option:: subformat
-
-    Specifies which VMDK subformat to use. Valid options are
-    ``monolithicSparse`` (default),
-    ``monolithicFlat``,
-    ``twoGbMaxExtentSparse``,
-    ``twoGbMaxExtentFlat`` and
-    ``streamOptimized``.
-
-.. program:: image-formats
-.. option:: vpc
-
-  VirtualPC compatible image format (VHD).
-
-  Supported options:
-
-  .. program:: vpc
-  .. option:: subformat
-
-    Specifies which VHD subformat to use. Valid options are
-    ``dynamic`` (default) and ``fixed``.
-
-.. program:: image-formats
-.. option:: VHDX
-
-  Hyper-V compatible image format (VHDX).
-
-  Supported options:
-
-  .. program:: VHDX
-  .. option:: subformat
-
-    Specifies which VHDX subformat to use. Valid options are
-    ``dynamic`` (default) and ``fixed``.
-
-    .. option:: block_state_zero
-
-      Force use of payload blocks of type 'ZERO'.  Can be set to ``on`` (default)
-      or ``off``.  When set to ``off``, new blocks will be created as
-      ``PAYLOAD_BLOCK_NOT_PRESENT``, which means parsers are free to return
-      arbitrary data for those blocks.  Do not set to ``off`` when using
-      ``qemu-img convert`` with ``subformat=dynamic``.
-
-    .. option:: block_size
-
-      Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on
-      image size.
-
-    .. option:: log_size
-
-      Log size; min 1 MB.
-
-Read-only formats
------------------
-
-More disk image file formats are supported in a read-only mode.
-
-.. program:: image-formats
-.. option:: bochs
-
-  Bochs images of ``growing`` type.
-
-.. program:: image-formats
-.. option:: cloop
-
-  Linux Compressed Loop image, useful only to reuse directly compressed
-  CD-ROM images present for example in the Knoppix CD-ROMs.
-
-.. program:: image-formats
-.. option:: dmg
-
-  Apple disk image.
-
-.. program:: image-formats
-.. option:: parallels
-
-  Parallels disk image format.
-
-Using host drives
------------------
-
-In addition to disk image files, QEMU can directly access host
-devices. We describe here the usage for QEMU version >= 0.8.3.
-
-Linux
-'''''
-
-On Linux, you can directly use the host device filename instead of a
-disk image filename provided you have enough privileges to access
-it. For example, use ``/dev/cdrom`` to access to the CDROM.
-
-CD
-  You can specify a CDROM device even if no CDROM is loaded. QEMU has
-  specific code to detect CDROM insertion or removal. CDROM ejection by
-  the guest OS is supported. Currently only data CDs are supported.
-
-Floppy
-  You can specify a floppy device even if no floppy is loaded. Floppy
-  removal is currently not detected accurately (if you change floppy
-  without doing floppy access while the floppy is not loaded, the guest
-  OS will think that the same floppy is loaded).
-  Use of the host's floppy device is deprecated, and support for it will
-  be removed in a future release.
-
-Hard disks
-  Hard disks can be used. Normally you must specify the whole disk
-  (``/dev/hdb`` instead of ``/dev/hdb1``) so that the guest OS can
-  see it as a partitioned disk. WARNING: unless you know what you do, it
-  is better to only make READ-ONLY accesses to the hard disk otherwise
-  you may corrupt your host data (use the ``-snapshot`` command
-  line option or modify the device permissions accordingly).
-
-Windows
-'''''''
-
-CD
-  The preferred syntax is the drive letter (e.g. ``d:``). The
-  alternate syntax ``\\.\d:`` is supported. ``/dev/cdrom`` is
-  supported as an alias to the first CDROM drive.
-
-  Currently there is no specific code to handle removable media, so it
-  is better to use the ``change`` or ``eject`` monitor commands to
-  change or eject media.
-
-Hard disks
-  Hard disks can be used with the syntax: ``\\.\PhysicalDriveN``
-  where *N* is the drive number (0 is the first hard disk).
-
-  WARNING: unless you know what you do, it is better to only make
-  READ-ONLY accesses to the hard disk otherwise you may corrupt your
-  host data (use the ``-snapshot`` command line so that the
-  modifications are written in a temporary file).
-
-Mac OS X
-''''''''
-
-``/dev/cdrom`` is an alias to the first CDROM.
-
-Currently there is no specific code to handle removable media, so it
-is better to use the ``change`` or ``eject`` monitor commands to
-change or eject media.
-
-Virtual FAT disk images
------------------------
-
-QEMU can automatically create a virtual FAT disk image from a
-directory tree. In order to use it, just type:
-
-.. parsed-literal::
-
-  |qemu_system| linux.img -hdb fat:/my_directory
-
-Then you access access to all the files in the ``/my_directory``
-directory without having to copy them in a disk image or to export
-them via SAMBA or NFS. The default access is *read-only*.
-
-Floppies can be emulated with the ``:floppy:`` option:
-
-.. parsed-literal::
-
-  |qemu_system| linux.img -fda fat:floppy:/my_directory
-
-A read/write support is available for testing (beta stage) with the
-``:rw:`` option:
-
-.. parsed-literal::
-
-  |qemu_system| linux.img -fda fat:floppy:rw:/my_directory
-
-What you should *never* do:
-
-- use non-ASCII filenames
-- use "-snapshot" together with ":rw:"
-- expect it to work when loadvm'ing
-- write to the FAT directory on the host system while accessing it with the guest system
-
-NBD access
-----------
-
-QEMU can access directly to block device exported using the Network Block Device
-protocol.
-
-.. parsed-literal::
-
-  |qemu_system| linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
-
-If the NBD server is located on the same host, you can use an unix socket instead
-of an inet socket:
-
-.. parsed-literal::
-
-  |qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
-
-In this case, the block device must be exported using qemu-nbd:
-
-.. parsed-literal::
-
-  qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
-
-The use of qemu-nbd allows sharing of a disk between several guests:
-
-.. parsed-literal::
-
-  qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
-
-and then you can use it with two guests:
-
-.. parsed-literal::
-
-  |qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
-  |qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
-
-If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
-own embedded NBD server), you must specify an export name in the URI:
-
-.. parsed-literal::
-
-  |qemu_system| -cdrom nbd://localhost/debian-500-ppc-netinst
-  |qemu_system| -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
-
-The URI syntax for NBD is supported since QEMU 1.3.  An alternative syntax is
-also available.  Here are some example of the older syntax:
-
-.. parsed-literal::
-
-  |qemu_system| linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
-  |qemu_system| linux2.img -hdb nbd:unix:/tmp/my_socket
-  |qemu_system| -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
-
-
-
-Sheepdog disk images
---------------------
-
-Sheepdog is a distributed storage system for QEMU.  It provides highly
-available block level storage volumes that can be attached to
-QEMU-based virtual machines.
-
-You can create a Sheepdog disk image with the command:
-
-.. parsed-literal::
-
-  qemu-img create sheepdog:///IMAGE SIZE
-
-where *IMAGE* is the Sheepdog image name and *SIZE* is its
-size.
-
-To import the existing *FILENAME* to Sheepdog, you can use a
-convert command.
-
-.. parsed-literal::
-
-  qemu-img convert FILENAME sheepdog:///IMAGE
-
-You can boot from the Sheepdog disk image with the command:
-
-.. parsed-literal::
-
-  |qemu_system| sheepdog:///IMAGE
-
-You can also create a snapshot of the Sheepdog image like qcow2.
-
-.. parsed-literal::
-
-  qemu-img snapshot -c TAG sheepdog:///IMAGE
-
-where *TAG* is a tag name of the newly created snapshot.
-
-To boot from the Sheepdog snapshot, specify the tag name of the
-snapshot.
-
-.. parsed-literal::
-
-  |qemu_system| sheepdog:///IMAGE#TAG
-
-You can create a cloned image from the existing snapshot.
-
-.. parsed-literal::
-
-  qemu-img create -b sheepdog:///BASE#TAG sheepdog:///IMAGE
-
-where *BASE* is an image name of the source snapshot and *TAG*
-is its tag name.
-
-You can use an unix socket instead of an inet socket:
-
-.. parsed-literal::
-
-  |qemu_system| sheepdog+unix:///IMAGE?socket=PATH
-
-If the Sheepdog daemon doesn't run on the local host, you need to
-specify one of the Sheepdog servers to connect to.
-
-.. parsed-literal::
-
-  qemu-img create sheepdog://HOSTNAME:PORT/IMAGE SIZE
-  |qemu_system| sheepdog://HOSTNAME:PORT/IMAGE
-
-iSCSI LUNs
-----------
-
-iSCSI is a popular protocol used to access SCSI devices across a computer
-network.
-
-There are two different ways iSCSI devices can be used by QEMU.
-
-The first method is to mount the iSCSI LUN on the host, and make it appear as
-any other ordinary SCSI device on the host and then to access this device as a
-/dev/sd device from QEMU. How to do this differs between host OSes.
-
-The second method involves using the iSCSI initiator that is built into
-QEMU. This provides a mechanism that works the same way regardless of which
-host OS you are running QEMU on. This section will describe this second method
-of using iSCSI together with QEMU.
-
-In QEMU, iSCSI devices are described using special iSCSI URLs. URL syntax:
-
-::
-
-  iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn-name>/<lun>
-
-Username and password are optional and only used if your target is set up
-using CHAP authentication for access control.
-Alternatively the username and password can also be set via environment
-variables to have these not show up in the process list:
-
-::
-
-  export LIBISCSI_CHAP_USERNAME=<username>
-  export LIBISCSI_CHAP_PASSWORD=<password>
-  iscsi://<host>/<target-iqn-name>/<lun>
-
-Various session related parameters can be set via special options, either
-in a configuration file provided via '-readconfig' or directly on the
-command line.
-
-If the initiator-name is not specified qemu will use a default name
-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.
-
-Setting a specific initiator name to use when logging in to the target:
-
-::
-
-  -iscsi initiator-name=iqn.qemu.test:my-initiator
-
-Controlling which type of header digest to negotiate with the target:
-
-::
-
-  -iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
-
-These can also be set via a configuration file:
-
-::
-
-  [iscsi]
-    user = "CHAP username"
-    password = "CHAP password"
-    initiator-name = "iqn.qemu.test:my-initiator"
-    # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
-    header-digest = "CRC32C"
-
-Setting the target name allows different options for different targets:
-
-::
-
-  [iscsi "iqn.target.name"]
-    user = "CHAP username"
-    password = "CHAP password"
-    initiator-name = "iqn.qemu.test:my-initiator"
-    # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
-    header-digest = "CRC32C"
-
-How to use a configuration file to set iSCSI configuration options:
-
-.. parsed-literal::
-
-  cat >iscsi.conf <<EOF
-  [iscsi]
-    user = "me"
-    password = "my password"
-    initiator-name = "iqn.qemu.test:my-initiator"
-    header-digest = "CRC32C"
-  EOF
-
-  |qemu_system| -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
-    -readconfig iscsi.conf
-
-How to set up a simple iSCSI target on loopback and access it via QEMU:
-this example shows how to set up an iSCSI target with one CDROM and one DISK
-using the Linux STGT software target. This target is available on Red Hat based
-systems as the package 'scsi-target-utils'.
-
-.. parsed-literal::
-
-  tgtd --iscsi portal=127.0.0.1:3260
-  tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
-  tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \\
-      -b /IMAGES/disk.img --device-type=disk
-  tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \\
-      -b /IMAGES/cd.iso --device-type=cd
-  tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
-
-  |qemu_system| -iscsi initiator-name=iqn.qemu.test:my-initiator \\
-    -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
-    -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
-
-GlusterFS disk images
----------------------
-
-GlusterFS is a user space distributed file system.
-
-You can boot from the GlusterFS disk image with the command:
-
-URI:
-
-.. parsed-literal::
-
-  |qemu_system| -drive file=gluster[+TYPE]://[HOST}[:PORT]]/VOLUME/PATH
-                               [?socket=...][,file.debug=9][,file.logfile=...]
-
-JSON:
-
-.. parsed-literal::
-
-  |qemu_system| 'json:{"driver":"qcow2",
-                           "file":{"driver":"gluster",
-                                    "volume":"testvol","path":"a.img","debug":9,"logfile":"...",
-                                    "server":[{"type":"tcp","host":"...","port":"..."},
-                                              {"type":"unix","socket":"..."}]}}'
-
-*gluster* is the protocol.
-
-*TYPE* specifies the transport type used to connect to gluster
-management daemon (glusterd). Valid transport types are
-tcp and unix. In the URI form, if a transport type isn't specified,
-then tcp type is assumed.
-
-*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 *HOST* field should not be specified.
-Instead *socket* field needs to be populated with the path to unix domain
-socket.
-
-*PORT* is the port number on which glusterd is listening. This is optional
-and if not specified, it defaults to port 24007. If the transport type is unix,
-then *PORT* should not be specified.
-
-*VOLUME* is the name of the gluster volume which contains the disk image.
-
-*PATH* is the path to the actual disk image that resides on gluster volume.
-
-*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
-
-*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.
-
-You can create a GlusterFS disk image with the command:
-
-.. parsed-literal::
-
-  qemu-img create gluster://HOST/VOLUME/PATH SIZE
-
-Examples
-
-.. parsed-literal::
-
-  |qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img
-  |qemu_system| -drive file=gluster+tcp://1.2.3.4/testvol/a.img
-  |qemu_system| -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
-  |qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
-  |qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
-  |qemu_system| -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
-  |qemu_system| -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
-  |qemu_system| -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
-  |qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
-  |qemu_system| '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| -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
-
-Secure Shell (ssh) disk images
-------------------------------
-
-You can access disk images located on a remote ssh server
-by using the ssh protocol:
-
-.. parsed-literal::
-
-  |qemu_system| -drive file=ssh://[USER@]SERVER[:PORT]/PATH[?host_key_check=HOST_KEY_CHECK]
-
-Alternative syntax using properties:
-
-.. parsed-literal::
-
-  |qemu_system| -drive file.driver=ssh[,file.user=USER],file.host=SERVER[,file.port=PORT],file.path=PATH[,file.host_key_check=HOST_KEY_CHECK]
-
-*ssh* is the protocol.
-
-*USER* is the remote user.  If not specified, then the local
-username is tried.
-
-*SERVER* specifies the remote ssh server.  Any ssh server can be
-used, but it must implement the sftp-server protocol.  Most Unix/Linux
-systems should work without requiring any extra configuration.
-
-*PORT* is the port number on which sshd is listening.  By default
-the standard ssh port (22) is used.
-
-*PATH* is the path to the disk image.
-
-The optional *HOST_KEY_CHECK* parameter controls how the remote
-host's key is checked.  The default is ``yes`` which means to use
-the local ``.ssh/known_hosts`` file.  Setting this to ``no``
-turns off known-hosts checking.  Or you can check that the host key
-matches a specific fingerprint:
-``host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8``
-(``sha1:`` can also be used as a prefix, but note that OpenSSH
-tools only use MD5 to print fingerprints).
-
-Currently authentication must be done using ssh-agent.  Other
-authentication methods may be supported in future.
-
-Note: Many ssh servers do not support an ``fsync``-style operation.
-The ssh driver cannot guarantee that disk flush requests are
-obeyed, and this causes a risk of disk corruption if the remote
-server or network goes down during writes.  The driver will
-print a warning when ``fsync`` is not supported:
-
-::
-
-  warning: ssh server ssh.example.com:22 does not support fsync
-
-With sufficiently new versions of libssh and OpenSSH, ``fsync`` is
-supported.
-
-NVMe disk images
-----------------
-
-NVM Express (NVMe) storage controllers can be accessed directly by a userspace
-driver in QEMU.  This bypasses the host kernel file system and block layers
-while retaining QEMU block layer functionalities, such as block jobs, I/O
-throttling, image formats, etc.  Disk I/O performance is typically higher than
-with ``-drive file=/dev/sda`` using either thread pool or linux-aio.
-
-The controller will be exclusively used by the QEMU process once started. To be
-able to share storage between multiple VMs and other applications on the host,
-please use the file based protocols.
-
-Before starting QEMU, bind the host NVMe controller to the host vfio-pci
-driver.  For example:
-
-.. parsed-literal::
-
-  # modprobe vfio-pci
-  # lspci -n -s 0000:06:0d.0
-  06:0d.0 0401: 1102:0002 (rev 08)
-  # echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
-  # echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
-
-  # |qemu_system| -drive file=nvme://HOST:BUS:SLOT.FUNC/NAMESPACE
-
-Alternative syntax using properties:
-
-.. parsed-literal::
-
-  |qemu_system| -drive file.driver=nvme,file.device=HOST:BUS:SLOT.FUNC,file.namespace=NAMESPACE
-
-*HOST*:*BUS*:*SLOT*.\ *FUNC* is the NVMe controller's PCI device
-address on the host.
-
-*NAMESPACE* is the NVMe namespace number, starting from 1.
-
-Disk image file locking
------------------------
-
-By default, QEMU tries to protect image files from unexpected concurrent
-access, as long as it's supported by the block protocol driver and host
-operating system. If multiple QEMU processes (including QEMU emulators and
-utilities) try to open the same image with conflicting accessing modes, all but
-the first one will get an error.
-
-This feature is currently supported by the file protocol on Linux with the Open
-File Descriptor (OFD) locking API, and can be configured to fall back to POSIX
-locking if the POSIX host doesn't support Linux OFD locking.
-
-To explicitly enable image locking, specify "locking=on" in the file protocol
-driver options. If OFD locking is not possible, a warning will be printed and
-the POSIX locking API will be used. In this case there is a risk that the lock
-will get silently lost when doing hot plugging and block jobs, due to the
-shortcomings of the POSIX locking API.
-
-QEMU transparently handles lock handover during shared storage migration.  For
-shared virtual disk images between multiple VMs, the "share-rw" device option
-should be used.
-
-By default, the guest has exclusive write access to its disk image. If the
-guest can safely share the disk image with other writers the
-``-device ...,share-rw=on`` parameter can be used.  This is only safe if
-the guest is running software, such as a cluster file system, that
-coordinates disk accesses to avoid corruption.
-
-Note that share-rw=on only declares the guest's ability to share the disk.
-Some QEMU features, such as image file formats, require exclusive write access
-to the disk image and this is unaffected by the share-rw=on option.
-
-Alternatively, locking can be fully disabled by "locking=off" block device
-option. In the command line, the option is usually in the form of
-"file.locking=off" as the protocol driver is normally placed as a "file" child
-under a format driver. For example:
-
-::
+Synopsis
+--------
 
-  -blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file
+QEMU block driver reference manual
 
-To check if image locking is active, check the output of the "lslocks" command
-on host and see if there are locks held by the QEMU process on the image file.
-More than one byte could be locked by the QEMU instance, each byte of which
-reflects a particular permission that is acquired or protected by the running
-block driver.
+Description
+-----------
 
-.. only:: man
+.. include:: qemu-block-drivers.rst.inc
 
-  See also
-  --------
+See also
+--------
 
-  The HTML documentation of QEMU for more precise information and Linux
-  user mode emulator invocation.
+The HTML documentation of QEMU for more precise information and Linux
+user mode emulator invocation.
diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
new file mode 100644
index 0000000000..b052a6d14e
--- /dev/null
+++ b/docs/system/qemu-block-drivers.rst.inc
@@ -0,0 +1,954 @@
+Disk image file formats
+~~~~~~~~~~~~~~~~~~~~~~~
+
+QEMU supports many image file formats that can be used with VMs as well as with
+any of the tools (like ``qemu-img``). This includes the preferred formats
+raw and qcow2 as well as formats that are supported for compatibility with
+older QEMU versions or other hypervisors.
+
+Depending on the image format, different options can be passed to
+``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option.
+This section describes each format and the options that are supported for it.
+
+.. program:: image-formats
+.. option:: raw
+
+  Raw disk image format. This format has the advantage of
+  being simple and easily exportable to all other emulators. If your
+  file system supports *holes* (for example in ext2 or ext3 on
+  Linux or NTFS on Windows), then only the written sectors will reserve
+  space. Use ``qemu-img info`` to know the real size used by the
+  image or ``ls -ls`` on Unix/Linux.
+
+  Supported options:
+
+  .. program:: raw
+  .. option:: preallocation
+
+    Preallocation mode (allowed values: ``off``, ``falloc``,
+    ``full``). ``falloc`` mode preallocates space for image by
+    calling ``posix_fallocate()``. ``full`` mode preallocates space
+    for image by writing data to underlying storage. This data may or
+    may not be zero, depending on the storage location.
+
+.. program:: image-formats
+.. option:: qcow2
+
+  QEMU image format, the most versatile format. Use it to have smaller
+  images (useful if your filesystem does not supports holes, for example
+  on Windows), zlib based compression and support of multiple VM
+  snapshots.
+
+  Supported options:
+
+  .. program:: qcow2
+  .. option:: compat
+
+    Determines the qcow2 version to use. ``compat=0.10`` uses the
+    traditional image format that can be read by any QEMU since 0.10.
+    ``compat=1.1`` enables image format extensions that only QEMU 1.1 and
+    newer understand (this is the default). Amongst others, this includes
+    zero clusters, which allow efficient copy-on-read for sparse images.
+
+  .. option:: backing_file
+
+    File name of a base image (see ``create`` subcommand)
+
+  .. option:: backing_fmt
+
+    Image format of the base image
+
+  .. option:: encryption
+
+    This option is deprecated and equivalent to ``encrypt.format=aes``
+
+  .. option:: encrypt.format
+
+    If this is set to ``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 ``encrypt.key-secret``
+    parameter. LUKS encryption parameters can be tuned with the other
+    ``encrypt.*`` parameters.
+
+    If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
+    The encryption key is given by the ``encrypt.key-secret`` parameter.
+    This encryption format is considered to be flawed by modern cryptography
+    standards, suffering from a number of design problems:
+
+    - The AES-CBC cipher is used with predictable initialization vectors based
+      on the sector number. This makes it vulnerable to chosen plaintext attacks
+      which can reveal the existence of encrypted data.
+    - The user passphrase is directly used as the encryption key. A poorly
+      chosen or short passphrase will compromise the security of the encryption.
+    - In the event of the passphrase being compromised there is no way to
+      change the passphrase to protect data in any qcow images. The files must
+      be cloned, using a different encryption passphrase in the new file. The
+      original file must then be securely erased using a program like shred,
+      though even this is ineffective with many modern storage technologies.
+
+    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 ``luks`` format
+    should be used instead.
+
+  .. option:: encrypt.key-secret
+
+    Provides the ID of a ``secret`` object that contains the passphrase
+    (``encrypt.format=luks``) or encryption key (``encrypt.format=aes``).
+
+  .. option:: encrypt.cipher-alg
+
+    Name of the cipher algorithm and key length. Currently defaults
+    to ``aes-256``. Only used when ``encrypt.format=luks``.
+
+  .. option:: encrypt.cipher-mode
+
+    Name of the encryption mode to use. Currently defaults to ``xts``.
+    Only used when ``encrypt.format=luks``.
+
+  .. option:: encrypt.ivgen-alg
+
+    Name of the initialization vector generator algorithm. Currently defaults
+    to ``plain64``. Only used when ``encrypt.format=luks``.
+
+  .. option:: encrypt.ivgen-hash-alg
+
+    Name of the hash algorithm to use with the initialization vector generator
+    (if required). Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
+
+  .. option:: encrypt.hash-alg
+
+    Name of the hash algorithm to use for PBKDF algorithm
+    Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
+
+  .. option:: encrypt.iter-time
+
+    Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
+    Defaults to ``2000``. Only used when ``encrypt.format=luks``.
+
+  .. option:: cluster_size
+
+    Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
+    sizes can improve the image file size whereas larger cluster sizes generally
+    provide better performance.
+
+  .. option:: preallocation
+
+    Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``,
+    ``full``). An image with preallocated metadata is initially larger but can
+    improve performance when the image needs to grow. ``falloc`` and ``full``
+    preallocations are like the same options of ``raw`` format, but sets up
+    metadata also.
+
+  .. option:: lazy_refcounts
+
+    If this option is set to ``on``, reference count updates are postponed with
+    the goal of avoiding metadata I/O and improving performance. This is
+    particularly interesting with :option:`cache=writethrough` which doesn't batch
+    metadata updates. The tradeoff is that after a host crash, the reference count
+    tables must be rebuilt, i.e. on the next open an (automatic) ``qemu-img
+    check -r all`` is required, which may take some time.
+
+    This option can only be enabled if ``compat=1.1`` is specified.
+
+  .. option:: nocow
+
+    If this option is set to ``on``, it will turn off COW of the file. It's only
+    valid on btrfs, no effect on other file systems.
+
+    Btrfs has low performance when hosting a VM image file, even more
+    when the guest on the VM also using btrfs as file system. Turning off
+    COW is a way to mitigate this bad performance. Generally there are two
+    ways to turn off COW on btrfs:
+
+    - Disable it by mounting with nodatacow, then all newly created files
+      will be NOCOW.
+    - For an empty file, add the NOCOW file attribute. That's what this
+      option does.
+
+    Note: this option is only valid to new or empty files. If there is
+    an existing file which is COW and has data blocks already, it couldn't
+    be changed to NOCOW by setting ``nocow=on``. One can issue ``lsattr
+    filename`` to check if the NOCOW flag is set or not (Capital 'C' is
+    NOCOW flag).
+
+.. program:: image-formats
+.. option:: qed
+
+   Old QEMU image format with support for backing files and compact image files
+   (when your filesystem or transport medium does not support holes).
+
+   When converting QED images to qcow2, you might want to consider using the
+   ``lazy_refcounts=on`` option to get a more QED-like behaviour.
+
+   Supported options:
+
+   .. program:: qed
+   .. option:: backing_file
+
+      File name of a base image (see ``create`` subcommand).
+
+   .. option:: backing_fmt
+
+     Image file format of backing file (optional).  Useful if the format cannot be
+     autodetected because it has no header, like some vhd/vpc files.
+
+   .. option:: cluster_size
+
+     Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
+     cluster sizes can improve the image file size whereas larger cluster sizes
+     generally provide better performance.
+
+   .. option:: table_size
+
+     Changes the number of clusters per L1/L2 table (must be
+     power-of-2 between 1 and 16).  There is normally no need to
+     change this value but this option can between used for
+     performance benchmarking.
+
+.. program:: image-formats
+.. option:: qcow
+
+  Old QEMU image format with support for backing files, compact image files,
+  encryption and compression.
+
+  Supported options:
+
+   .. program:: qcow
+   .. option:: backing_file
+
+     File name of a base image (see ``create`` subcommand)
+
+   .. option:: encryption
+
+     This option is deprecated and equivalent to ``encrypt.format=aes``
+
+   .. option:: encrypt.format
+
+     If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
+     The encryption key is given by the ``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 ``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 ``qcow2`` format
+     instead with ``encrypt.format=luks``.
+
+   .. option:: encrypt.key-secret
+
+     Provides the ID of a ``secret`` object that contains the encryption
+     key (``encrypt.format=aes``).
+
+.. program:: image-formats
+.. option:: luks
+
+  LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
+
+  Supported options:
+
+  .. program:: luks
+  .. option:: key-secret
+
+    Provides the ID of a ``secret`` object that contains the passphrase.
+
+  .. option:: cipher-alg
+
+    Name of the cipher algorithm and key length. Currently defaults
+    to ``aes-256``.
+
+  .. option:: cipher-mode
+
+    Name of the encryption mode to use. Currently defaults to ``xts``.
+
+  .. option:: ivgen-alg
+
+    Name of the initialization vector generator algorithm. Currently defaults
+    to ``plain64``.
+
+  .. option:: ivgen-hash-alg
+
+    Name of the hash algorithm to use with the initialization vector generator
+    (if required). Defaults to ``sha256``.
+
+  .. option:: hash-alg
+
+    Name of the hash algorithm to use for PBKDF algorithm
+    Defaults to ``sha256``.
+
+  .. option:: iter-time
+
+    Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
+    Defaults to ``2000``.
+
+.. program:: image-formats
+.. option:: vdi
+
+  VirtualBox 1.1 compatible image format.
+
+  Supported options:
+
+  .. program:: vdi
+  .. option:: static
+
+    If this option is set to ``on``, the image is created with metadata
+    preallocation.
+
+.. program:: image-formats
+.. option:: vmdk
+
+  VMware 3 and 4 compatible image format.
+
+  Supported options:
+
+  .. program: vmdk
+  .. option:: backing_file
+
+    File name of a base image (see ``create`` subcommand).
+
+  .. option:: compat6
+
+    Create a VMDK version 6 image (instead of version 4)
+
+  .. option:: hwversion
+
+    Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
+    if hwversion is specified.
+
+  .. option:: subformat
+
+    Specifies which VMDK subformat to use. Valid options are
+    ``monolithicSparse`` (default),
+    ``monolithicFlat``,
+    ``twoGbMaxExtentSparse``,
+    ``twoGbMaxExtentFlat`` and
+    ``streamOptimized``.
+
+.. program:: image-formats
+.. option:: vpc
+
+  VirtualPC compatible image format (VHD).
+
+  Supported options:
+
+  .. program:: vpc
+  .. option:: subformat
+
+    Specifies which VHD subformat to use. Valid options are
+    ``dynamic`` (default) and ``fixed``.
+
+.. program:: image-formats
+.. option:: VHDX
+
+  Hyper-V compatible image format (VHDX).
+
+  Supported options:
+
+  .. program:: VHDX
+  .. option:: subformat
+
+    Specifies which VHDX subformat to use. Valid options are
+    ``dynamic`` (default) and ``fixed``.
+
+    .. option:: block_state_zero
+
+      Force use of payload blocks of type 'ZERO'.  Can be set to ``on`` (default)
+      or ``off``.  When set to ``off``, new blocks will be created as
+      ``PAYLOAD_BLOCK_NOT_PRESENT``, which means parsers are free to return
+      arbitrary data for those blocks.  Do not set to ``off`` when using
+      ``qemu-img convert`` with ``subformat=dynamic``.
+
+    .. option:: block_size
+
+      Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on
+      image size.
+
+    .. option:: log_size
+
+      Log size; min 1 MB.
+
+Read-only formats
+~~~~~~~~~~~~~~~~~
+
+More disk image file formats are supported in a read-only mode.
+
+.. program:: image-formats
+.. option:: bochs
+
+  Bochs images of ``growing`` type.
+
+.. program:: image-formats
+.. option:: cloop
+
+  Linux Compressed Loop image, useful only to reuse directly compressed
+  CD-ROM images present for example in the Knoppix CD-ROMs.
+
+.. program:: image-formats
+.. option:: dmg
+
+  Apple disk image.
+
+.. program:: image-formats
+.. option:: parallels
+
+  Parallels disk image format.
+
+Using host drives
+~~~~~~~~~~~~~~~~~
+
+In addition to disk image files, QEMU can directly access host
+devices. We describe here the usage for QEMU version >= 0.8.3.
+
+Linux
+^^^^^
+
+On Linux, you can directly use the host device filename instead of a
+disk image filename provided you have enough privileges to access
+it. For example, use ``/dev/cdrom`` to access to the CDROM.
+
+CD
+  You can specify a CDROM device even if no CDROM is loaded. QEMU has
+  specific code to detect CDROM insertion or removal. CDROM ejection by
+  the guest OS is supported. Currently only data CDs are supported.
+
+Floppy
+  You can specify a floppy device even if no floppy is loaded. Floppy
+  removal is currently not detected accurately (if you change floppy
+  without doing floppy access while the floppy is not loaded, the guest
+  OS will think that the same floppy is loaded).
+  Use of the host's floppy device is deprecated, and support for it will
+  be removed in a future release.
+
+Hard disks
+  Hard disks can be used. Normally you must specify the whole disk
+  (``/dev/hdb`` instead of ``/dev/hdb1``) so that the guest OS can
+  see it as a partitioned disk. WARNING: unless you know what you do, it
+  is better to only make READ-ONLY accesses to the hard disk otherwise
+  you may corrupt your host data (use the ``-snapshot`` command
+  line option or modify the device permissions accordingly).
+
+Windows
+^^^^^^^
+
+CD
+  The preferred syntax is the drive letter (e.g. ``d:``). The
+  alternate syntax ``\\.\d:`` is supported. ``/dev/cdrom`` is
+  supported as an alias to the first CDROM drive.
+
+  Currently there is no specific code to handle removable media, so it
+  is better to use the ``change`` or ``eject`` monitor commands to
+  change or eject media.
+
+Hard disks
+  Hard disks can be used with the syntax: ``\\.\PhysicalDriveN``
+  where *N* is the drive number (0 is the first hard disk).
+
+  WARNING: unless you know what you do, it is better to only make
+  READ-ONLY accesses to the hard disk otherwise you may corrupt your
+  host data (use the ``-snapshot`` command line so that the
+  modifications are written in a temporary file).
+
+Mac OS X
+^^^^^^^^
+
+``/dev/cdrom`` is an alias to the first CDROM.
+
+Currently there is no specific code to handle removable media, so it
+is better to use the ``change`` or ``eject`` monitor commands to
+change or eject media.
+
+Virtual FAT disk images
+~~~~~~~~~~~~~~~~~~~~~~~
+
+QEMU can automatically create a virtual FAT disk image from a
+directory tree. In order to use it, just type:
+
+.. parsed-literal::
+
+  |qemu_system| linux.img -hdb fat:/my_directory
+
+Then you access access to all the files in the ``/my_directory``
+directory without having to copy them in a disk image or to export
+them via SAMBA or NFS. The default access is *read-only*.
+
+Floppies can be emulated with the ``:floppy:`` option:
+
+.. parsed-literal::
+
+  |qemu_system| linux.img -fda fat:floppy:/my_directory
+
+A read/write support is available for testing (beta stage) with the
+``:rw:`` option:
+
+.. parsed-literal::
+
+  |qemu_system| linux.img -fda fat:floppy:rw:/my_directory
+
+What you should *never* do:
+
+- use non-ASCII filenames
+- use "-snapshot" together with ":rw:"
+- expect it to work when loadvm'ing
+- write to the FAT directory on the host system while accessing it with the guest system
+
+NBD access
+~~~~~~~~~~
+
+QEMU can access directly to block device exported using the Network Block Device
+protocol.
+
+.. parsed-literal::
+
+  |qemu_system| linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
+
+If the NBD server is located on the same host, you can use an unix socket instead
+of an inet socket:
+
+.. parsed-literal::
+
+  |qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
+
+In this case, the block device must be exported using qemu-nbd:
+
+.. parsed-literal::
+
+  qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
+
+The use of qemu-nbd allows sharing of a disk between several guests:
+
+.. parsed-literal::
+
+  qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
+
+and then you can use it with two guests:
+
+.. parsed-literal::
+
+  |qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
+  |qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
+
+If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
+own embedded NBD server), you must specify an export name in the URI:
+
+.. parsed-literal::
+
+  |qemu_system| -cdrom nbd://localhost/debian-500-ppc-netinst
+  |qemu_system| -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
+
+The URI syntax for NBD is supported since QEMU 1.3.  An alternative syntax is
+also available.  Here are some example of the older syntax:
+
+.. parsed-literal::
+
+  |qemu_system| linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
+  |qemu_system| linux2.img -hdb nbd:unix:/tmp/my_socket
+  |qemu_system| -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
+
+
+
+Sheepdog disk images
+~~~~~~~~~~~~~~~~~~~~
+
+Sheepdog is a distributed storage system for QEMU.  It provides highly
+available block level storage volumes that can be attached to
+QEMU-based virtual machines.
+
+You can create a Sheepdog disk image with the command:
+
+.. parsed-literal::
+
+  qemu-img create sheepdog:///IMAGE SIZE
+
+where *IMAGE* is the Sheepdog image name and *SIZE* is its
+size.
+
+To import the existing *FILENAME* to Sheepdog, you can use a
+convert command.
+
+.. parsed-literal::
+
+  qemu-img convert FILENAME sheepdog:///IMAGE
+
+You can boot from the Sheepdog disk image with the command:
+
+.. parsed-literal::
+
+  |qemu_system| sheepdog:///IMAGE
+
+You can also create a snapshot of the Sheepdog image like qcow2.
+
+.. parsed-literal::
+
+  qemu-img snapshot -c TAG sheepdog:///IMAGE
+
+where *TAG* is a tag name of the newly created snapshot.
+
+To boot from the Sheepdog snapshot, specify the tag name of the
+snapshot.
+
+.. parsed-literal::
+
+  |qemu_system| sheepdog:///IMAGE#TAG
+
+You can create a cloned image from the existing snapshot.
+
+.. parsed-literal::
+
+  qemu-img create -b sheepdog:///BASE#TAG sheepdog:///IMAGE
+
+where *BASE* is an image name of the source snapshot and *TAG*
+is its tag name.
+
+You can use an unix socket instead of an inet socket:
+
+.. parsed-literal::
+
+  |qemu_system| sheepdog+unix:///IMAGE?socket=PATH
+
+If the Sheepdog daemon doesn't run on the local host, you need to
+specify one of the Sheepdog servers to connect to.
+
+.. parsed-literal::
+
+  qemu-img create sheepdog://HOSTNAME:PORT/IMAGE SIZE
+  |qemu_system| sheepdog://HOSTNAME:PORT/IMAGE
+
+iSCSI LUNs
+~~~~~~~~~~
+
+iSCSI is a popular protocol used to access SCSI devices across a computer
+network.
+
+There are two different ways iSCSI devices can be used by QEMU.
+
+The first method is to mount the iSCSI LUN on the host, and make it appear as
+any other ordinary SCSI device on the host and then to access this device as a
+/dev/sd device from QEMU. How to do this differs between host OSes.
+
+The second method involves using the iSCSI initiator that is built into
+QEMU. This provides a mechanism that works the same way regardless of which
+host OS you are running QEMU on. This section will describe this second method
+of using iSCSI together with QEMU.
+
+In QEMU, iSCSI devices are described using special iSCSI URLs. URL syntax:
+
+::
+
+  iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn-name>/<lun>
+
+Username and password are optional and only used if your target is set up
+using CHAP authentication for access control.
+Alternatively the username and password can also be set via environment
+variables to have these not show up in the process list:
+
+::
+
+  export LIBISCSI_CHAP_USERNAME=<username>
+  export LIBISCSI_CHAP_PASSWORD=<password>
+  iscsi://<host>/<target-iqn-name>/<lun>
+
+Various session related parameters can be set via special options, either
+in a configuration file provided via '-readconfig' or directly on the
+command line.
+
+If the initiator-name is not specified qemu will use a default name
+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.
+
+Setting a specific initiator name to use when logging in to the target:
+
+::
+
+  -iscsi initiator-name=iqn.qemu.test:my-initiator
+
+Controlling which type of header digest to negotiate with the target:
+
+::
+
+  -iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
+
+These can also be set via a configuration file:
+
+::
+
+  [iscsi]
+    user = "CHAP username"
+    password = "CHAP password"
+    initiator-name = "iqn.qemu.test:my-initiator"
+    # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
+    header-digest = "CRC32C"
+
+Setting the target name allows different options for different targets:
+
+::
+
+  [iscsi "iqn.target.name"]
+    user = "CHAP username"
+    password = "CHAP password"
+    initiator-name = "iqn.qemu.test:my-initiator"
+    # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
+    header-digest = "CRC32C"
+
+How to use a configuration file to set iSCSI configuration options:
+
+.. parsed-literal::
+
+  cat >iscsi.conf <<EOF
+  [iscsi]
+    user = "me"
+    password = "my password"
+    initiator-name = "iqn.qemu.test:my-initiator"
+    header-digest = "CRC32C"
+  EOF
+
+  |qemu_system| -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
+    -readconfig iscsi.conf
+
+How to set up a simple iSCSI target on loopback and access it via QEMU:
+this example shows how to set up an iSCSI target with one CDROM and one DISK
+using the Linux STGT software target. This target is available on Red Hat based
+systems as the package 'scsi-target-utils'.
+
+.. parsed-literal::
+
+  tgtd --iscsi portal=127.0.0.1:3260
+  tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
+  tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \\
+      -b /IMAGES/disk.img --device-type=disk
+  tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \\
+      -b /IMAGES/cd.iso --device-type=cd
+  tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
+
+  |qemu_system| -iscsi initiator-name=iqn.qemu.test:my-initiator \\
+    -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
+    -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
+
+GlusterFS disk images
+~~~~~~~~~~~~~~~~~~~~~
+
+GlusterFS is a user space distributed file system.
+
+You can boot from the GlusterFS disk image with the command:
+
+URI:
+
+.. parsed-literal::
+
+  |qemu_system| -drive file=gluster[+TYPE]://[HOST}[:PORT]]/VOLUME/PATH
+                               [?socket=...][,file.debug=9][,file.logfile=...]
+
+JSON:
+
+.. parsed-literal::
+
+  |qemu_system| 'json:{"driver":"qcow2",
+                           "file":{"driver":"gluster",
+                                    "volume":"testvol","path":"a.img","debug":9,"logfile":"...",
+                                    "server":[{"type":"tcp","host":"...","port":"..."},
+                                              {"type":"unix","socket":"..."}]}}'
+
+*gluster* is the protocol.
+
+*TYPE* specifies the transport type used to connect to gluster
+management daemon (glusterd). Valid transport types are
+tcp and unix. In the URI form, if a transport type isn't specified,
+then tcp type is assumed.
+
+*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 *HOST* field should not be specified.
+Instead *socket* field needs to be populated with the path to unix domain
+socket.
+
+*PORT* is the port number on which glusterd is listening. This is optional
+and if not specified, it defaults to port 24007. If the transport type is unix,
+then *PORT* should not be specified.
+
+*VOLUME* is the name of the gluster volume which contains the disk image.
+
+*PATH* is the path to the actual disk image that resides on gluster volume.
+
+*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
+
+*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.
+
+You can create a GlusterFS disk image with the command:
+
+.. parsed-literal::
+
+  qemu-img create gluster://HOST/VOLUME/PATH SIZE
+
+Examples
+
+.. parsed-literal::
+
+  |qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img
+  |qemu_system| -drive file=gluster+tcp://1.2.3.4/testvol/a.img
+  |qemu_system| -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
+  |qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
+  |qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
+  |qemu_system| -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
+  |qemu_system| -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
+  |qemu_system| -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
+  |qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
+  |qemu_system| '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| -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
+
+Secure Shell (ssh) disk images
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can access disk images located on a remote ssh server
+by using the ssh protocol:
+
+.. parsed-literal::
+
+  |qemu_system| -drive file=ssh://[USER@]SERVER[:PORT]/PATH[?host_key_check=HOST_KEY_CHECK]
+
+Alternative syntax using properties:
+
+.. parsed-literal::
+
+  |qemu_system| -drive file.driver=ssh[,file.user=USER],file.host=SERVER[,file.port=PORT],file.path=PATH[,file.host_key_check=HOST_KEY_CHECK]
+
+*ssh* is the protocol.
+
+*USER* is the remote user.  If not specified, then the local
+username is tried.
+
+*SERVER* specifies the remote ssh server.  Any ssh server can be
+used, but it must implement the sftp-server protocol.  Most Unix/Linux
+systems should work without requiring any extra configuration.
+
+*PORT* is the port number on which sshd is listening.  By default
+the standard ssh port (22) is used.
+
+*PATH* is the path to the disk image.
+
+The optional *HOST_KEY_CHECK* parameter controls how the remote
+host's key is checked.  The default is ``yes`` which means to use
+the local ``.ssh/known_hosts`` file.  Setting this to ``no``
+turns off known-hosts checking.  Or you can check that the host key
+matches a specific fingerprint:
+``host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8``
+(``sha1:`` can also be used as a prefix, but note that OpenSSH
+tools only use MD5 to print fingerprints).
+
+Currently authentication must be done using ssh-agent.  Other
+authentication methods may be supported in future.
+
+Note: Many ssh servers do not support an ``fsync``-style operation.
+The ssh driver cannot guarantee that disk flush requests are
+obeyed, and this causes a risk of disk corruption if the remote
+server or network goes down during writes.  The driver will
+print a warning when ``fsync`` is not supported:
+
+::
+
+  warning: ssh server ssh.example.com:22 does not support fsync
+
+With sufficiently new versions of libssh and OpenSSH, ``fsync`` is
+supported.
+
+NVMe disk images
+~~~~~~~~~~~~~~~~
+
+NVM Express (NVMe) storage controllers can be accessed directly by a userspace
+driver in QEMU.  This bypasses the host kernel file system and block layers
+while retaining QEMU block layer functionalities, such as block jobs, I/O
+throttling, image formats, etc.  Disk I/O performance is typically higher than
+with ``-drive file=/dev/sda`` using either thread pool or linux-aio.
+
+The controller will be exclusively used by the QEMU process once started. To be
+able to share storage between multiple VMs and other applications on the host,
+please use the file based protocols.
+
+Before starting QEMU, bind the host NVMe controller to the host vfio-pci
+driver.  For example:
+
+.. parsed-literal::
+
+  # modprobe vfio-pci
+  # lspci -n -s 0000:06:0d.0
+  06:0d.0 0401: 1102:0002 (rev 08)
+  # echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
+  # echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
+
+  # |qemu_system| -drive file=nvme://HOST:BUS:SLOT.FUNC/NAMESPACE
+
+Alternative syntax using properties:
+
+.. parsed-literal::
+
+  |qemu_system| -drive file.driver=nvme,file.device=HOST:BUS:SLOT.FUNC,file.namespace=NAMESPACE
+
+*HOST*:*BUS*:*SLOT*.\ *FUNC* is the NVMe controller's PCI device
+address on the host.
+
+*NAMESPACE* is the NVMe namespace number, starting from 1.
+
+Disk image file locking
+~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, QEMU tries to protect image files from unexpected concurrent
+access, as long as it's supported by the block protocol driver and host
+operating system. If multiple QEMU processes (including QEMU emulators and
+utilities) try to open the same image with conflicting accessing modes, all but
+the first one will get an error.
+
+This feature is currently supported by the file protocol on Linux with the Open
+File Descriptor (OFD) locking API, and can be configured to fall back to POSIX
+locking if the POSIX host doesn't support Linux OFD locking.
+
+To explicitly enable image locking, specify "locking=on" in the file protocol
+driver options. If OFD locking is not possible, a warning will be printed and
+the POSIX locking API will be used. In this case there is a risk that the lock
+will get silently lost when doing hot plugging and block jobs, due to the
+shortcomings of the POSIX locking API.
+
+QEMU transparently handles lock handover during shared storage migration.  For
+shared virtual disk images between multiple VMs, the "share-rw" device option
+should be used.
+
+By default, the guest has exclusive write access to its disk image. If the
+guest can safely share the disk image with other writers the
+``-device ...,share-rw=on`` parameter can be used.  This is only safe if
+the guest is running software, such as a cluster file system, that
+coordinates disk accesses to avoid corruption.
+
+Note that share-rw=on only declares the guest's ability to share the disk.
+Some QEMU features, such as image file formats, require exclusive write access
+to the disk image and this is unaffected by the share-rw=on option.
+
+Alternatively, locking can be fully disabled by "locking=off" block device
+option. In the command line, the option is usually in the form of
+"file.locking=off" as the protocol driver is normally placed as a "file" child
+under a format driver. For example:
+
+::
+
+  -blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file
+
+To check if image locking is active, check the output of the "lslocks" command
+on host and see if there are locks held by the QEMU process on the image file.
+More than one byte could be locked by the QEMU instance, each byte of which
+reflects a particular permission that is acquired or protected by the running
+block driver.
diff --git a/docs/system/qemu-cpu-models.rst b/docs/system/qemu-cpu-models.rst
new file mode 100644
index 0000000000..53d7538c47
--- /dev/null
+++ b/docs/system/qemu-cpu-models.rst
@@ -0,0 +1,20 @@
+:orphan:
+
+QEMU / KVM CPU model configuration
+==================================
+
+Synopsis
+''''''''
+
+QEMU CPU Modelling Infrastructure manual
+
+Description
+'''''''''''
+
+.. include:: cpu-models-x86.rst.inc
+.. include:: cpu-models-mips.rst.inc
+
+See also
+''''''''
+
+The HTML documentation of QEMU for more precise information and Linux user mode emulator invocation.
diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst
new file mode 100644
index 0000000000..e9a25d0680
--- /dev/null
+++ b/docs/system/qemu-manpage.rst
@@ -0,0 +1,45 @@
+:orphan:
+
+..
+   This file is the skeleton for the qemu.1 manpage. It mostly
+   should simply include the .rst.inc files corresponding to the
+   parts of the documentation that go in the manpage as well as the
+   HTML manual.
+
+Title
+=====
+
+Synopsis
+--------
+
+.. parsed-literal::
+
+   |qemu_system| [options] [disk_image]
+
+Description
+-----------
+
+.. include:: target-i386-desc.rst.inc
+
+Options
+-------
+
+disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
+not need a disk image.
+
+.. hxtool-doc:: qemu-options.hx
+
+.. include:: keys.rst.inc
+
+.. include:: mux-chardev.rst.inc
+
+Notes
+-----
+
+.. include:: device-url-syntax.rst.inc
+
+See also
+--------
+
+The HTML documentation of QEMU for more precise information and Linux
+user mode emulator invocation.
diff --git a/docs/system/quickstart.rst b/docs/system/quickstart.rst
new file mode 100644
index 0000000000..3a3acab5e7
--- /dev/null
+++ b/docs/system/quickstart.rst
@@ -0,0 +1,13 @@
+.. _pcsys_005fquickstart:
+
+Quick Start
+-----------
+
+Download and uncompress a PC hard disk image with Linux installed (e.g.
+``linux.img``) and type:
+
+.. parsed-literal::
+
+   |qemu_system| linux.img
+
+Linux should boot and give you a prompt.
diff --git a/docs/system/security.rst b/docs/system/security.rst
new file mode 100644
index 0000000000..f2092c8768
--- /dev/null
+++ b/docs/system/security.rst
@@ -0,0 +1,173 @@
+Security
+========
+
+Overview
+--------
+
+This chapter explains the security requirements that QEMU is designed to meet
+and principles for securely deploying QEMU.
+
+Security Requirements
+---------------------
+
+QEMU supports many different use cases, some of which have stricter security
+requirements than others.  The community has agreed on the overall security
+requirements that users may depend on.  These requirements define what is
+considered supported from a security perspective.
+
+Virtualization Use Case
+'''''''''''''''''''''''
+
+The virtualization use case covers cloud and virtual private server (VPS)
+hosting, as well as traditional data center and desktop virtualization.  These
+use cases rely on hardware virtualization extensions to execute guest code
+safely on the physical CPU at close-to-native speed.
+
+The following entities are untrusted, meaning that they may be buggy or
+malicious:
+
+- Guest
+- User-facing interfaces (e.g. VNC, SPICE, WebSocket)
+- Network protocols (e.g. NBD, live migration)
+- User-supplied files (e.g. disk images, kernels, device trees)
+- Passthrough devices (e.g. PCI, USB)
+
+Bugs affecting these entities are evaluated on whether they can cause damage in
+real-world use cases and treated as security bugs if this is the case.
+
+Non-virtualization Use Case
+'''''''''''''''''''''''''''
+
+The non-virtualization use case covers emulation using the Tiny Code Generator
+(TCG).  In principle the TCG and device emulation code used in conjunction with
+the non-virtualization use case should meet the same security requirements as
+the virtualization use case.  However, for historical reasons much of the
+non-virtualization use case code was not written with these security
+requirements in mind.
+
+Bugs affecting the non-virtualization use case are not considered security
+bugs at this time.  Users with non-virtualization use cases must not rely on
+QEMU to provide guest isolation or any security guarantees.
+
+Architecture
+------------
+
+This section describes the design principles that ensure the security
+requirements are met.
+
+Guest Isolation
+'''''''''''''''
+
+Guest isolation is the confinement of guest code to the virtual machine.  When
+guest code gains control of execution on the host this is called escaping the
+virtual machine.  Isolation also includes resource limits such as throttling of
+CPU, memory, disk, or network.  Guests must be unable to exceed their resource
+limits.
+
+QEMU presents an attack surface to the guest in the form of emulated devices.
+The guest must not be able to gain control of QEMU.  Bugs in emulated devices
+could allow malicious guests to gain code execution in QEMU.  At this point the
+guest has escaped the virtual machine and is able to act in the context of the
+QEMU process on the host.
+
+Guests often interact with other guests and share resources with them.  A
+malicious guest must not gain control of other guests or access their data.
+Disk image files and network traffic must be protected from other guests unless
+explicitly shared between them by the user.
+
+Principle of Least Privilege
+''''''''''''''''''''''''''''
+
+The principle of least privilege states that each component only has access to
+the privileges necessary for its function.  In the case of QEMU this means that
+each process only has access to resources belonging to the guest.
+
+The QEMU process should not have access to any resources that are inaccessible
+to the guest.  This way the guest does not gain anything by escaping into the
+QEMU process since it already has access to those same resources from within
+the guest.
+
+Following the principle of least privilege immediately fulfills guest isolation
+requirements.  For example, guest A only has access to its own disk image file
+``a.img`` and not guest B's disk image file ``b.img``.
+
+In reality certain resources are inaccessible to the guest but must be
+available to QEMU to perform its function.  For example, host system calls are
+necessary for QEMU but are not exposed to guests.  A guest that escapes into
+the QEMU process can then begin invoking host system calls.
+
+New features must be designed to follow the principle of least privilege.
+Should this not be possible for technical reasons, the security risk must be
+clearly documented so users are aware of the trade-off of enabling the feature.
+
+Isolation mechanisms
+''''''''''''''''''''
+
+Several isolation mechanisms are available to realize this architecture of
+guest isolation and the principle of least privilege.  With the exception of
+Linux seccomp, these mechanisms are all deployed by management tools that
+launch QEMU, such as libvirt.  They are also platform-specific so they are only
+described briefly for Linux here.
+
+The fundamental isolation mechanism is that QEMU processes must run as
+unprivileged users.  Sometimes it seems more convenient to launch QEMU as
+root to give it access to host devices (e.g. ``/dev/net/tun``) but this poses a
+huge security risk.  File descriptor passing can be used to give an otherwise
+unprivileged QEMU process access to host devices without running QEMU as root.
+It is also possible to launch QEMU as a non-root user and configure UNIX groups
+for access to ``/dev/kvm``, ``/dev/net/tun``, and other device nodes.
+Some Linux distros already ship with UNIX groups for these devices by default.
+
+- SELinux and AppArmor make it possible to confine processes beyond the
+  traditional UNIX process and file permissions model.  They restrict the QEMU
+  process from accessing processes and files on the host system that are not
+  needed by QEMU.
+
+- Resource limits and cgroup controllers provide throughput and utilization
+  limits on key resources such as CPU time, memory, and I/O bandwidth.
+
+- Linux namespaces can be used to make process, file system, and other system
+  resources unavailable to QEMU.  A namespaced QEMU process is restricted to only
+  those resources that were granted to it.
+
+- Linux seccomp is available via the QEMU ``--sandbox`` option.  It disables
+  system calls that are not needed by QEMU, thereby reducing the host kernel
+  attack surface.
+
+Sensitive configurations
+------------------------
+
+There are aspects of QEMU that can have security implications which users &
+management applications must be aware of.
+
+Monitor console (QMP and HMP)
+'''''''''''''''''''''''''''''
+
+The monitor console (whether used with QMP or HMP) provides an interface
+to dynamically control many aspects of QEMU's runtime operation. Many of the
+commands exposed will instruct QEMU to access content on the host file system
+and/or trigger spawning of external processes.
+
+For example, the ``migrate`` command allows for the spawning of arbitrary
+processes for the purpose of tunnelling the migration data stream. The
+``blockdev-add`` command instructs QEMU to open arbitrary files, exposing
+their content to the guest as a virtual disk.
+
+Unless QEMU is otherwise confined using technologies such as SELinux, AppArmor,
+or Linux namespaces, the monitor console should be considered to have privileges
+equivalent to those of the user account QEMU is running under.
+
+It is further important to consider the security of the character device backend
+over which the monitor console is exposed. It needs to have protection against
+malicious third parties which might try to make unauthorized connections, or
+perform man-in-the-middle attacks. Many of the character device backends do not
+satisfy this requirement and so must not be used for the monitor console.
+
+The general recommendation is that the monitor console should be exposed over
+a UNIX domain socket backend to the local host only. Use of the TCP based
+character device backend is inappropriate unless configured to use both TLS
+encryption and authorization control policy on client connections.
+
+In summary, the monitor console is considered a privileged control interface to
+QEMU and as such should only be made accessible to a trusted management
+application or user.
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
new file mode 100644
index 0000000000..d2a3b44ce8
--- /dev/null
+++ b/docs/system/target-arm.rst
@@ -0,0 +1,217 @@
+.. _ARM-System-emulator:
+
+ARM System emulator
+-------------------
+
+Use the executable ``qemu-system-arm`` to simulate a ARM machine. The
+ARM Integrator/CP board is emulated with the following devices:
+
+-  ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
+
+-  Two PL011 UARTs
+
+-  SMC 91c111 Ethernet adapter
+
+-  PL110 LCD controller
+
+-  PL050 KMI with PS/2 keyboard and mouse.
+
+-  PL181 MultiMedia Card Interface with SD card.
+
+The ARM Versatile baseboard is emulated with the following devices:
+
+-  ARM926E, ARM1136 or Cortex-A8 CPU
+
+-  PL190 Vectored Interrupt Controller
+
+-  Four PL011 UARTs
+
+-  SMC 91c111 Ethernet adapter
+
+-  PL110 LCD controller
+
+-  PL050 KMI with PS/2 keyboard and mouse.
+
+-  PCI host bridge. Note the emulated PCI bridge only provides access
+   to PCI memory space. It does not provide access to PCI IO space. This
+   means some devices (eg. ne2k_pci NIC) are not usable, and others (eg.
+   rtl8139 NIC) are only usable when the guest drivers use the memory
+   mapped control registers.
+
+-  PCI OHCI USB controller.
+
+-  LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
+   devices.
+
+-  PL181 MultiMedia Card Interface with SD card.
+
+Several variants of the ARM RealView baseboard are emulated, including
+the EB, PB-A8 and PBX-A9. Due to interactions with the bootloader, only
+certain Linux kernel configurations work out of the box on these boards.
+
+Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
+enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
+should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
+disabled and expect 1024M RAM.
+
+The following devices are emulated:
+
+-  ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
+
+-  ARM AMBA Generic/Distributed Interrupt Controller
+
+-  Four PL011 UARTs
+
+-  SMC 91c111 or SMSC LAN9118 Ethernet adapter
+
+-  PL110 LCD controller
+
+-  PL050 KMI with PS/2 keyboard and mouse
+
+-  PCI host bridge
+
+-  PCI OHCI USB controller
+
+-  LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
+   devices
+
+-  PL181 MultiMedia Card Interface with SD card.
+
+The XScale-based clamshell PDA models (\"Spitz\", \"Akita\", \"Borzoi\"
+and \"Terrier\") emulation includes the following peripherals:
+
+-  Intel PXA270 System-on-chip (ARM V5TE core)
+
+-  NAND Flash memory
+
+-  IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in \"Akita\"
+
+-  On-chip OHCI USB controller
+
+-  On-chip LCD controller
+
+-  On-chip Real Time Clock
+
+-  TI ADS7846 touchscreen controller on SSP bus
+
+-  Maxim MAX1111 analog-digital converter on |I2C| bus
+
+-  GPIO-connected keyboard controller and LEDs
+
+-  Secure Digital card connected to PXA MMC/SD host
+
+-  Three on-chip UARTs
+
+-  WM8750 audio CODEC on |I2C| and |I2S| busses
+
+The Palm Tungsten|E PDA (codename \"Cheetah\") emulation includes the
+following elements:
+
+-  Texas Instruments OMAP310 System-on-chip (ARM 925T core)
+
+-  ROM and RAM memories (ROM firmware image can be loaded with
+   -option-rom)
+
+-  On-chip LCD controller
+
+-  On-chip Real Time Clock
+
+-  TI TSC2102i touchscreen controller / analog-digital converter /
+   Audio CODEC, connected through MicroWire and |I2S| busses
+
+-  GPIO-connected matrix keypad
+
+-  Secure Digital card connected to OMAP MMC/SD host
+
+-  Three on-chip UARTs
+
+Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 /
+48) emulation supports the following elements:
+
+-  Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
+
+-  RAM and non-volatile OneNAND Flash memories
+
+-  Display connected to EPSON remote framebuffer chip and OMAP on-chip
+   display controller and a LS041y3 MIPI DBI-C controller
+
+-  TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen
+   controllers driven through SPI bus
+
+-  National Semiconductor LM8323-controlled qwerty keyboard driven
+   through |I2C| bus
+
+-  Secure Digital card connected to OMAP MMC/SD host
+
+-  Three OMAP on-chip UARTs and on-chip STI debugging console
+
+-  Mentor Graphics \"Inventra\" dual-role USB controller embedded in a
+   TI TUSB6010 chip - only USB host mode is supported
+
+-  TI TMP105 temperature sensor driven through |I2C| bus
+
+-  TI TWL92230C power management companion with an RTC on
+   |I2C| bus
+
+-  Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
+   through CBUS
+
+The Luminary Micro Stellaris LM3S811EVB emulation includes the following
+devices:
+
+-  Cortex-M3 CPU core.
+
+-  64k Flash and 8k SRAM.
+
+-  Timers, UARTs, ADC and |I2C| interface.
+
+-  OSRAM Pictiva 96x16 OLED with SSD0303 controller on
+   |I2C| bus.
+
+The Luminary Micro Stellaris LM3S6965EVB emulation includes the
+following devices:
+
+-  Cortex-M3 CPU core.
+
+-  256k Flash and 64k SRAM.
+
+-  Timers, UARTs, ADC, |I2C| and SSI interfaces.
+
+-  OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via
+   SSI.
+
+The Freecom MusicPal internet radio emulation includes the following
+elements:
+
+-  Marvell MV88W8618 ARM core.
+
+-  32 MB RAM, 256 KB SRAM, 8 MB flash.
+
+-  Up to 2 16550 UARTs
+
+-  MV88W8xx8 Ethernet controller
+
+-  MV88W8618 audio controller, WM8750 CODEC and mixer
+
+-  128x64 display with brightness control
+
+-  2 buttons, 2 navigation wheels with button function
+
+The Siemens SX1 models v1 and v2 (default) basic emulation. The
+emulation includes the following elements:
+
+-  Texas Instruments OMAP310 System-on-chip (ARM 925T core)
+
+-  ROM and RAM memories (ROM firmware image can be loaded with
+   -pflash) V1 1 Flash of 16MB and 1 Flash of 8MB V2 1 Flash of 32MB
+
+-  On-chip LCD controller
+
+-  On-chip Real Time Clock
+
+-  Secure Digital card connected to OMAP MMC/SD host
+
+-  Three on-chip UARTs
+
+A Linux 2.6 test image is available on the QEMU web site. More
+information is available in the QEMU mailing-list archive.
diff --git a/docs/system/target-i386-desc.rst.inc b/docs/system/target-i386-desc.rst.inc
new file mode 100644
index 0000000000..47a169e0ae
--- /dev/null
+++ b/docs/system/target-i386-desc.rst.inc
@@ -0,0 +1,62 @@
+The QEMU PC System emulator simulates the following peripherals:
+
+-  i440FX host PCI bridge and PIIX3 PCI to ISA bridge
+
+-  Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
+   extensions (hardware level, including all non standard modes).
+
+-  PS/2 mouse and keyboard
+
+-  2 PCI IDE interfaces with hard disk and CD-ROM support
+
+-  Floppy disk
+
+-  PCI and ISA network adapters
+
+-  Serial ports
+
+-  IPMI BMC, either and internal or external one
+
+-  Creative SoundBlaster 16 sound card
+
+-  ENSONIQ AudioPCI ES1370 sound card
+
+-  Intel 82801AA AC97 Audio compatible sound card
+
+-  Intel HD Audio Controller and HDA codec
+
+-  Adlib (OPL2) - Yamaha YM3812 compatible chip
+
+-  Gravis Ultrasound GF1 sound card
+
+-  CS4231A compatible sound card
+
+-  PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1
+   hub.
+
+SMP is supported with up to 255 CPUs.
+
+QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
+VGA BIOS.
+
+QEMU uses YM3812 emulation by Tatsuyuki Satoh.
+
+QEMU uses GUS emulation (GUSEMU32 http://www.deinmeister.de/gusemu/) by
+Tibor \"TS\" Schütz.
+
+Note that, by default, GUS shares IRQ(7) with parallel ports and so QEMU
+must be told to not have parallel ports to have working GUS.
+
+.. parsed-literal::
+
+   |qemu_system_x86| dos.img -soundhw gus -parallel none
+
+Alternatively:
+
+.. parsed-literal::
+
+   |qemu_system_x86| dos.img -device gus,irq=5
+
+Or some other unclaimed IRQ.
+
+CS4231A is the chip used in Windows Sound System and GUSMAX products
diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst
new file mode 100644
index 0000000000..51be03d881
--- /dev/null
+++ b/docs/system/target-i386.rst
@@ -0,0 +1,23 @@
+.. _QEMU-PC-System-emulator:
+
+x86 (PC) System emulator
+------------------------
+
+.. _pcsys_005fdevices:
+
+Peripherals
+~~~~~~~~~~~
+
+.. include:: target-i386-desc.rst.inc
+
+.. include:: cpu-models-x86.rst.inc
+
+.. _pcsys_005freq:
+
+OS requirements
+~~~~~~~~~~~~~~~
+
+On x86_64 hosts, the default set of CPU features enabled by the KVM
+accelerator require the host to be running Linux v4.5 or newer. Red Hat
+Enterprise Linux 7 is also supported, since the required
+functionality was backported.
diff --git a/docs/system/target-m68k.rst b/docs/system/target-m68k.rst
new file mode 100644
index 0000000000..d28d3b92e5
--- /dev/null
+++ b/docs/system/target-m68k.rst
@@ -0,0 +1,21 @@
+.. _ColdFire-System-emulator:
+
+ColdFire System emulator
+------------------------
+
+Use the executable ``qemu-system-m68k`` to simulate a ColdFire machine.
+The emulator is able to boot a uClinux kernel.
+
+The M5208EVB emulation includes the following devices:
+
+-  MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
+
+-  Three Two on-chip UARTs.
+
+-  Fast Ethernet Controller (FEC)
+
+The AN5206 emulation includes the following devices:
+
+-  MCF5206 ColdFire V2 Microprocessor.
+
+-  Two on-chip UARTs.
diff --git a/docs/system/target-mips.rst b/docs/system/target-mips.rst
new file mode 100644
index 0000000000..2736fd0509
--- /dev/null
+++ b/docs/system/target-mips.rst
@@ -0,0 +1,120 @@
+.. _MIPS-System-emulator:
+
+MIPS System emulator
+--------------------
+
+Four executables cover simulation of 32 and 64-bit MIPS systems in both
+endian options, ``qemu-system-mips``, ``qemu-system-mipsel``
+``qemu-system-mips64`` and ``qemu-system-mips64el``. Five different
+machine types are emulated:
+
+-  A generic ISA PC-like machine \"mips\"
+
+-  The MIPS Malta prototype board \"malta\"
+
+-  An ACER Pica \"pica61\". This machine needs the 64-bit emulator.
+
+-  MIPS emulator pseudo board \"mipssim\"
+
+-  A MIPS Magnum R4000 machine \"magnum\". This machine needs the
+   64-bit emulator.
+
+The generic emulation is supported by Debian 'Etch' and is able to
+install Debian into a virtual disk image. The following devices are
+emulated:
+
+-  A range of MIPS CPUs, default is the 24Kf
+
+-  PC style serial port
+
+-  PC style IDE disk
+
+-  NE2000 network card
+
+The Malta emulation supports the following devices:
+
+-  Core board with MIPS 24Kf CPU and Galileo system controller
+
+-  PIIX4 PCI/USB/SMbus controller
+
+-  The Multi-I/O chip's serial device
+
+-  PCI network cards (PCnet32 and others)
+
+-  Malta FPGA serial device
+
+-  Cirrus (default) or any other PCI VGA graphics card
+
+The Boston board emulation supports the following devices:
+
+-  Xilinx FPGA, which includes a PCIe root port and an UART
+
+-  Intel EG20T PCH connects the I/O peripherals, but only the SATA bus
+   is emulated
+
+The ACER Pica emulation supports:
+
+-  MIPS R4000 CPU
+
+-  PC-style IRQ and DMA controllers
+
+-  PC Keyboard
+
+-  IDE controller
+
+The MIPS Magnum R4000 emulation supports:
+
+-  MIPS R4000 CPU
+
+-  PC-style IRQ controller
+
+-  PC Keyboard
+
+-  SCSI controller
+
+-  G364 framebuffer
+
+The Fulong 2E emulation supports:
+
+-  Loongson 2E CPU
+
+-  Bonito64 system controller as North Bridge
+
+-  VT82C686 chipset as South Bridge
+
+-  RTL8139D as a network card chipset
+
+The mipssim pseudo board emulation provides an environment similar to
+what the proprietary MIPS emulator uses for running Linux. It supports:
+
+-  A range of MIPS CPUs, default is the 24Kf
+
+-  PC style serial port
+
+-  MIPSnet network emulation
+
+.. include:: cpu-models-mips.rst.inc
+
+.. _nanoMIPS-System-emulator:
+
+nanoMIPS System emulator
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Executable ``qemu-system-mipsel`` also covers simulation of 32-bit
+nanoMIPS system in little endian mode:
+
+-  nanoMIPS I7200 CPU
+
+Example of ``qemu-system-mipsel`` usage for nanoMIPS is shown below:
+
+Download ``<disk_image_file>`` from
+https://mipsdistros.mips.com/LinuxDistro/nanomips/buildroot/index.html.
+
+Download ``<kernel_image_file>`` from
+https://mipsdistros.mips.com/LinuxDistro/nanomips/kernels/v4.15.18-432-gb2eb9a8b07a1-20180627102142/index.html.
+
+Start system emulation of Malta board with nanoMIPS I7200 CPU::
+
+   qemu-system-mipsel -cpu I7200 -kernel <kernel_image_file> \
+       -M malta -serial stdio -m <memory_size> -hda <disk_image_file> \
+       -append "mem=256m@0x0 rw console=ttyS0 vga=cirrus vesa=0x111 root=/dev/sda"
diff --git a/docs/system/target-ppc.rst b/docs/system/target-ppc.rst
new file mode 100644
index 0000000000..a2f04c533c
--- /dev/null
+++ b/docs/system/target-ppc.rst
@@ -0,0 +1,47 @@
+.. _PowerPC-System-emulator:
+
+PowerPC System emulator
+-----------------------
+
+Use the executable ``qemu-system-ppc`` to simulate a complete 40P (PREP)
+or PowerMac PowerPC system.
+
+QEMU emulates the following PowerMac peripherals:
+
+-  UniNorth or Grackle PCI Bridge
+
+-  PCI VGA compatible card with VESA Bochs Extensions
+
+-  2 PMAC IDE interfaces with hard disk and CD-ROM support
+
+-  NE2000 PCI adapters
+
+-  Non Volatile RAM
+
+-  VIA-CUDA with ADB keyboard and mouse.
+
+QEMU emulates the following 40P (PREP) peripherals:
+
+-  PCI Bridge
+
+-  PCI VGA compatible card with VESA Bochs Extensions
+
+-  2 IDE interfaces with hard disk and CD-ROM support
+
+-  Floppy disk
+
+-  PCnet network adapters
+
+-  Serial port
+
+-  PREP Non Volatile RAM
+
+-  PC compatible keyboard and mouse.
+
+Since version 0.9.1, QEMU uses OpenBIOS https://www.openbios.org/ for
+the g3beige and mac99 PowerMac and the 40p machines. OpenBIOS is a free
+(GPL v2) portable firmware implementation. The goal is to implement a
+100% IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
+
+More information is available at
+http://perso.magic.fr/l_indien/qemu-ppc/.
diff --git a/docs/system/target-sparc.rst b/docs/system/target-sparc.rst
new file mode 100644
index 0000000000..b55f8d09e9
--- /dev/null
+++ b/docs/system/target-sparc.rst
@@ -0,0 +1,62 @@
+.. _Sparc32-System-emulator:
+
+Sparc32 System emulator
+-----------------------
+
+Use the executable ``qemu-system-sparc`` to simulate the following Sun4m
+architecture machines:
+
+-  SPARCstation 4
+
+-  SPARCstation 5
+
+-  SPARCstation 10
+
+-  SPARCstation 20
+
+-  SPARCserver 600MP
+
+-  SPARCstation LX
+
+-  SPARCstation Voyager
+
+-  SPARCclassic
+
+-  SPARCbook
+
+The emulation is somewhat complete. SMP up to 16 CPUs is supported, but
+Linux limits the number of usable CPUs to 4.
+
+QEMU emulates the following sun4m peripherals:
+
+-  IOMMU
+
+-  TCX or cgthree Frame buffer
+
+-  Lance (Am7990) Ethernet
+
+-  Non Volatile RAM M48T02/M48T08
+
+-  Slave I/O: timers, interrupt controllers, Zilog serial ports,
+   keyboard and power/reset logic
+
+-  ESP SCSI controller with hard disk and CD-ROM support
+
+-  Floppy drive (not on SS-600MP)
+
+-  CS4231 sound device (only on SS-5, not working yet)
+
+The number of peripherals is fixed in the architecture. Maximum memory
+size depends on the machine type, for SS-5 it is 256MB and for others
+2047MB.
+
+Since version 0.8.2, QEMU uses OpenBIOS https://www.openbios.org/.
+OpenBIOS is a free (GPL v2) portable firmware implementation. The goal
+is to implement a 100% IEEE 1275-1994 (referred to as Open Firmware)
+compliant firmware.
+
+A sample Linux 2.6 series kernel and ram disk image are available on the
+QEMU web site. There are still issues with NetBSD and OpenBSD, but most
+kernel versions work. Please note that currently older Solaris kernels
+don't work probably due to interface issues between OpenBIOS and
+Solaris.
diff --git a/docs/system/target-sparc64.rst b/docs/system/target-sparc64.rst
new file mode 100644
index 0000000000..97e334b930
--- /dev/null
+++ b/docs/system/target-sparc64.rst
@@ -0,0 +1,37 @@
+.. _Sparc64-System-emulator:
+
+Sparc64 System emulator
+-----------------------
+
+Use the executable ``qemu-system-sparc64`` to simulate a Sun4u
+(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 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
+http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2
+and is able to boot the disk.s10hw2 Solaris image.
+
+::
+
+   qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
+                       -nographic -m 256 \
+                       -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
+
+QEMU emulates the following peripherals:
+
+-  UltraSparc IIi APB PCI Bridge
+
+-  PCI VGA compatible card with VESA Bochs Extensions
+
+-  PS/2 mouse and keyboard
+
+-  Non Volatile RAM M48T59
+
+-  PC-compatible serial ports
+
+-  2 PCI IDE interfaces with hard disk and CD-ROM support
+
+-  Floppy disk
diff --git a/docs/system/target-xtensa.rst b/docs/system/target-xtensa.rst
new file mode 100644
index 0000000000..8d703ad769
--- /dev/null
+++ b/docs/system/target-xtensa.rst
@@ -0,0 +1,27 @@
+.. _Xtensa-System-emulator:
+
+Xtensa System emulator
+----------------------
+
+Two executables cover simulation of both Xtensa endian options,
+``qemu-system-xtensa`` and ``qemu-system-xtensaeb``. Two different
+machine types are emulated:
+
+-  Xtensa emulator pseudo board \"sim\"
+
+-  Avnet LX60/LX110/LX200 board
+
+The sim pseudo board emulation provides an environment similar to one
+provided by the proprietary Tensilica ISS. It supports:
+
+-  A range of Xtensa CPUs, default is the DC232B
+
+-  Console and filesystem access via semihosting calls
+
+The Avnet LX60/LX110/LX200 emulation supports:
+
+-  A range of Xtensa CPUs, default is the DC232B
+
+-  16550 UART
+
+-  OpenCores 10/100 Mbps Ethernet MAC
diff --git a/docs/system/targets.rst b/docs/system/targets.rst
new file mode 100644
index 0000000000..eba3111247
--- /dev/null
+++ b/docs/system/targets.rst
@@ -0,0 +1,19 @@
+QEMU System Emulator Targets
+============================
+
+QEMU is a generic emulator and it emulates many machines. Most of the
+options are similar for all machines. Specific information about the
+various targets are mentioned in the following sections.
+
+Contents:
+
+.. toctree::
+
+   target-i386
+   target-ppc
+   target-sparc
+   target-sparc64
+   target-mips
+   target-arm
+   target-m68k
+   target-xtensa
diff --git a/docs/system/tls.rst b/docs/system/tls.rst
new file mode 100644
index 0000000000..dc2b94257f
--- /dev/null
+++ b/docs/system/tls.rst
@@ -0,0 +1,328 @@
+.. _network_005ftls:
+
+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 ``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
+``/etc/pki/qemu`` or for unprivileged users in ``$HOME/.pki/qemu``.
+
+.. _tls_005fgenerate_005fca:
+
+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 and secure. If this key is compromised the entire trust
+chain of the certificates issued with it is lost.
+
+::
+
+   # certtool --generate-privkey > ca-key.pem
+
+To generate a self-signed certificate requires one core piece of
+information, the name of the organization. A template file ``ca.info``
+should be populated with the desired data to avoid having to deal with
+interactive prompts from certtool::
+
+   # cat > ca.info <<EOF
+   cn = Name of your organization
+   ca
+   cert_signing_key
+   EOF
+   # certtool --generate-self-signed \
+              --load-privkey ca-key.pem
+              --template ca.info \
+              --outfile ca-cert.pem
+
+The ``ca`` keyword in the template sets the v3 basic constraints
+extension to indicate this certificate is for a CA, while
+``cert_signing_key`` sets the key usage extension to indicate this will
+be used for signing other keys. The generated ``ca-cert.pem`` file
+should be copied to all servers and clients wishing to utilize TLS
+support in the VNC server. The ``ca-key.pem`` must not be
+disclosed/copied anywhere except the host responsible for issuing
+certificates.
+
+.. _tls_005fgenerate_005fserver:
+
+Issuing server certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each server (or host) needs to be issued with a key and certificate.
+When connecting the certificate is sent to the client which validates it
+against the CA certificate. The core pieces of information for a server
+certificate are the hostnames and/or IP addresses that will be used by
+clients when connecting. The hostname / IP address that the client
+specifies when connecting will be validated against the hostname(s) and
+IP address(es) recorded in the server certificate, and if no match is
+found the client will close the connection.
+
+Thus it is recommended that the server certificate include both the
+fully qualified and unqualified hostnames. If the server will have
+permanently assigned IP address(es), and clients are likely to use them
+when connecting, they may also be included in the certificate. Both IPv4
+and IPv6 addresses are supported. Historically certificates only
+included 1 hostname in the ``CN`` field, however, usage of this field
+for validation is now deprecated. Instead modern TLS clients will
+validate against the Subject Alt Name extension data, which allows for
+multiple entries. In the future usage of the ``CN`` field may be
+discontinued entirely, so providing SAN extension data is strongly
+recommended.
+
+On the host holding the CA, create template files containing the
+information for each server, and use it to issue server certificates.
+
+::
+
+   # cat > server-hostNNN.info <<EOF
+   organization = Name  of your organization
+   cn = hostNNN.foo.example.com
+   dns_name = hostNNN
+   dns_name = hostNNN.foo.example.com
+   ip_address = 10.0.1.87
+   ip_address = 192.8.0.92
+   ip_address = 2620:0:cafe::87
+   ip_address = 2001:24::92
+   tls_www_server
+   encryption_key
+   signing_key
+   EOF
+   # 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-hostNNN-key.pem \
+              --template server-hostNNN.info \
+              --outfile server-hostNNN-cert.pem
+
+The ``dns_name`` and ``ip_address`` fields in the template are setting
+the subject alt name extension data. The ``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 ``encryption_key`` and ``signing_key`` keyword is
+the key usage extension to indicate this certificate is intended for
+usage in the data session.
+
+The ``server-hostNNN-key.pem`` and ``server-hostNNN-cert.pem`` files
+should now be securely copied to the server for which they were
+generated, and renamed to ``server-key.pem`` and ``server-cert.pem``
+when added to the ``/etc/pki/qemu`` directory on the target host. The
+``server-key.pem`` file is security sensitive and should be kept
+protected with file mode 0600 to prevent disclosure.
+
+.. _tls_005fgenerate_005fclient:
+
+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.
+
+::
+
+   # cat > client-hostNNN.info <<EOF
+   country = GB
+   state = London
+   locality = City Of London
+   organization = Name of your organization
+   cn = hostNNN.foo.example.com
+   tls_www_client
+   encryption_key
+   signing_key
+   EOF
+   # certtool --generate-privkey > 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
+
+The subject alt name extension data is not required for clients, so the
+the ``dns_name`` and ``ip_address`` fields are not included. The
+``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 ``encryption_key`` and ``signing_key`` keyword is the
+key usage extension to indicate this certificate is intended for usage
+in the data session.
+
+The ``client-hostNNN-key.pem`` and ``client-hostNNN-cert.pem`` files
+should now be securely copied to the client for which they were
+generated, and renamed to ``client-key.pem`` and ``client-cert.pem``
+when added to the ``/etc/pki/qemu`` directory on the target host. The
+``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.
+
+::
+
+   # cat > both-hostNNN.info <<EOF
+   country = GB
+   state = London
+   locality = City Of London
+   organization = Name of your organization
+   cn = hostNNN.foo.example.com
+   dns_name = hostNNN
+   dns_name = hostNNN.foo.example.com
+   ip_address = 10.0.1.87
+   ip_address = 192.8.0.92
+   ip_address = 2620:0:cafe::87
+   ip_address = 2001:24::92
+   tls_www_server
+   tls_www_client
+   encryption_key
+   signing_key
+   EOF
+   # certtool --generate-privkey > both-hostNNN-key.pem
+   # certtool --generate-certificate \
+              --load-ca-certificate ca-cert.pem \
+              --load-ca-privkey ca-key.pem \
+              --load-privkey both-hostNNN-key.pem \
+              --template both-hostNNN.info \
+              --outfile both-hostNNN-cert.pem
+
+When copying the PEM files to the target host, save them twice, once as
+``server-cert.pem`` and ``server-key.pem``, and again as
+``client-cert.pem`` and ``client-key.pem``.
+
+.. _tls_005fcreds_005fsetup:
+
+TLS x509 credential configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+QEMU has a standard mechanism for loading x509 credentials that will be
+used for network services and clients. It requires specifying the
+``tls-creds-x509`` class name to the ``--object`` command line argument
+for the system emulators. Each set of credentials loaded should be given
+a unique string identifier via the ``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.
+
+When specifying the object, the ``dir`` parameters specifies which
+directory contains the credential files. This directory is expected to
+contain files with the names mentioned previously, ``ca-cert.pem``,
+``server-key.pem``, ``server-cert.pem``, ``client-key.pem`` and
+``client-cert.pem`` as appropriate. It is also possible to include a set
+of pre-generated Diffie-Hellman (DH) parameters in a file
+``dh-params.pem``, which can be created using the
+``certtool --generate-dh-params`` command. If omitted, QEMU will
+dynamically generate DH parameters when loading the credentials.
+
+The ``endpoint`` parameter indicates whether the credentials will be
+used for a network client or server, and determines which PEM files are
+loaded.
+
+The ``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.
+
+To load server credentials with client certificate validation enabled
+
+.. parsed-literal::
+
+   |qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server
+
+while to load client credentials use
+
+.. parsed-literal::
+
+   |qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client
+
+Network services which support TLS will all have a ``tls-creds``
+parameter which expects the ID of the TLS credentials object. For
+example with VNC:
+
+.. parsed-literal::
+
+   |qemu_system| -vnc 0.0.0.0:0,tls-creds=tls0
+
+.. _tls_005fpsk:
+
+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 ``psktool`` program to generate a ``keys.psk`` file
+containing one or more usernames and random keys::
+
+   mkdir -m 0700 /tmp/keys
+   psktool -u rich -p /tmp/keys/keys.psk
+
+TLS-enabled servers such as qemu-nbd can use this directory like so::
+
+   qemu-nbd \
+     -t -x / \
+     --object tls-creds-psk,id=tls0,endpoint=server,dir=/tmp/keys \
+     --tls-creds tls0 \
+     image.qcow2
+
+When connecting from a qemu-based client you must specify the directory
+containing ``keys.psk`` and an optional username (defaults to "qemu")::
+
+   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=/
diff --git a/docs/system/usb.rst b/docs/system/usb.rst
new file mode 100644
index 0000000000..ddfa828d74
--- /dev/null
+++ b/docs/system/usb.rst
@@ -0,0 +1,137 @@
+.. _pcsys_005fusb:
+
+USB emulation
+-------------
+
+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.
+
+.. _usb_005fdevices:
+
+Connecting USB devices
+~~~~~~~~~~~~~~~~~~~~~~
+
+USB devices can be connected with the ``-device usb-...`` command line
+option or the ``device_add`` monitor command. Available devices are:
+
+``usb-mouse``
+   Virtual Mouse. This will override the PS/2 mouse emulation when
+   activated.
+
+``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.
+
+``usb-storage,drive=drive_id``
+   Mass storage device backed by drive_id (see
+   :ref:`disk_005fimages`)
+
+``usb-uas``
+   USB attached SCSI device, see
+   `usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
+   for details
+
+``usb-bot``
+   Bulk-only transport storage device, see
+   `usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
+   for details here, too
+
+``usb-mtp,rootdir=dir``
+   Media transfer protocol device, using dir as root of the file tree
+   that is presented to the guest.
+
+``usb-host,hostbus=bus,hostaddr=addr``
+   Pass through the host device identified by bus and addr
+
+``usb-host,vendorid=vendor,productid=product``
+   Pass through the host device identified by vendor and product ID
+
+``usb-wacom-tablet``
+   Virtual Wacom PenPartner tablet. This device is similar to the
+   ``tablet`` above but it can be used with the tslib library because in
+   addition to touch coordinates it reports touch pressure.
+
+``usb-kbd``
+   Standard USB keyboard. Will override the PS/2 keyboard (if present).
+
+``usb-serial,chardev=id``
+   Serial converter. This emulates an FTDI FT232BM chip connected to
+   host character device id.
+
+``usb-braille,chardev=id``
+   Braille device. This will use BrlAPI to display the braille output on
+   a real or fake device referenced by id.
+
+``usb-net[,netdev=id]``
+   Network adapter that supports CDC ethernet and RNDIS protocols. id
+   specifies a netdev defined with ``-netdev …,id=id``. For instance,
+   user-mode networking can be used with
+
+   .. parsed-literal::
+
+      |qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0
+
+``usb-ccid``
+   Smartcard reader device
+
+``usb-audio``
+   USB audio device
+
+.. _host_005fusb_005fdevices:
+
+Using host USB devices on a Linux host
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+WARNING: this is an experimental feature. QEMU will slow down when using
+it. USB devices requiring real time streaming (i.e. USB Video Cameras)
+are not supported yet.
+
+1. If you use an early Linux 2.4 kernel, verify that no Linux driver is
+   actually using the USB device. A simple way to do that is simply to
+   disable the corresponding kernel module by renaming it from
+   ``mydriver.o`` to ``mydriver.o.disabled``.
+
+2. Verify that ``/proc/bus/usb`` is working (most Linux distributions
+   should enable it by default). You should see something like that:
+
+   ::
+
+      ls /proc/bus/usb
+      001  devices  drivers
+
+3. Since only root can access to the USB devices directly, you can
+   either launch QEMU as root or change the permissions of the USB
+   devices you want to use. For testing, the following suffices:
+
+   ::
+
+      chown -R myuid /proc/bus/usb
+
+4. Launch QEMU and do in the monitor:
+
+   ::
+
+      info usbhost
+        Device 1.2, speed 480 Mb/s
+          Class 00: USB device 1234:5678, USB DISK
+
+   You should see the list of the devices you can use (Never try to use
+   hubs, it won't work).
+
+5. Add the device in QEMU by using:
+
+   ::
+
+      device_add usb-host,vendorid=0x1234,productid=0x5678
+
+   Normally the guest OS should report that a new USB device is plugged.
+   You can use the option ``-device usb-host,...`` to do the same.
+
+6. Now you can try to use the host USB device in QEMU.
+
+When relaunching QEMU, you may have to unplug and plug again the USB
+device to make it work again (this is a bug).
diff --git a/docs/system/vnc-security.rst b/docs/system/vnc-security.rst
new file mode 100644
index 0000000000..b237b07330
--- /dev/null
+++ b/docs/system/vnc-security.rst
@@ -0,0 +1,202 @@
+.. _vnc_005fsecurity:
+
+VNC security
+------------
+
+The VNC server capability provides access to the graphical console of
+the guest VM across the network. This has a number of security
+considerations depending on the deployment scenarios.
+
+.. _vnc_005fsec_005fnone:
+
+Without passwords
+~~~~~~~~~~~~~~~~~
+
+The simplest VNC server setup does not include any form of
+authentication. For this setup it is recommended to restrict it to
+listen on a UNIX domain socket only. For example
+
+.. parsed-literal::
+
+   |qemu_system| [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
+
+This ensures that only users on local box with read/write access to that
+path can access the VNC server. To securely access the VNC server from a
+remote machine, a combination of netcat+ssh can be used to provide a
+secure tunnel.
+
+.. _vnc_005fsec_005fpassword:
+
+With passwords
+~~~~~~~~~~~~~~
+
+The VNC protocol has limited support for password based authentication.
+Since the protocol limits passwords to 8 characters it should not be
+considered to provide high security. The password can be fairly easily
+brute-forced by a client making repeat connections. For this reason, a
+VNC server using password authentication should be restricted to only
+listen on the loopback interface or UNIX domain sockets. Password
+authentication is not supported when operating in FIPS 140-2 compliance
+mode as it requires the use of the DES cipher. Password authentication
+is requested with the ``password`` option, and then once QEMU is running
+the password is set with the monitor. Until the monitor is used to set
+the password all clients will be rejected.
+
+.. parsed-literal::
+
+   |qemu_system| [...OPTIONS...] -vnc :1,password -monitor stdio
+   (qemu) change vnc password
+   Password: ********
+   (qemu)
+
+.. _vnc_005fsec_005fcertificate:
+
+With x509 certificates
+~~~~~~~~~~~~~~~~~~~~~~
+
+The QEMU VNC server also implements the VeNCrypt extension allowing use
+of TLS for encryption of the session, and x509 certificates for
+authentication. The use of x509 certificates is strongly recommended,
+because TLS on its own is susceptible to man-in-the-middle attacks.
+Basic x509 certificate support provides a secure session, but no
+authentication. This allows any client to connect, and provides an
+encrypted session.
+
+.. parsed-literal::
+
+   |qemu_system| [...OPTIONS...] \
+     -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \
+     -vnc :1,tls-creds=tls0 -monitor stdio
+
+In the above example ``/etc/pki/qemu`` should contain at least three
+files, ``ca-cert.pem``, ``server-cert.pem`` and ``server-key.pem``.
+Unprivileged users will want to use a private directory, for example
+``$HOME/.pki/qemu``. NB the ``server-key.pem`` file should be protected
+with file mode 0600 to only be readable by the user owning it.
+
+.. _vnc_005fsec_005fcertificate_005fverify:
+
+With x509 certificates and client verification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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. It uses the same syntax as previously,
+but with ``verify-peer`` set to ``yes`` instead.
+
+.. parsed-literal::
+
+   |qemu_system| [...OPTIONS...] \
+     -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
+     -vnc :1,tls-creds=tls0 -monitor stdio
+
+.. _vnc_005fsec_005fcertificate_005fpw:
+
+With x509 certificates, client verification and passwords
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Finally, the previous method can be combined with VNC password
+authentication to provide two layers of authentication for clients.
+
+.. parsed-literal::
+
+   |qemu_system| [...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)
+
+.. _vnc_005fsec_005fsasl:
+
+With SASL authentication
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SASL authentication method is a VNC extension, that provides an
+easily extendable, pluggable authentication method. This allows for
+integration with a wide range of authentication mechanisms, such as PAM,
+GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more. The
+strength of the authentication depends on the exact mechanism
+configured. If the chosen mechanism also provides a SSF layer, then it
+will encrypt the datastream as well.
+
+Refer to the later docs on how to choose the exact SASL mechanism used
+for authentication, but assuming use of one supporting SSF, then QEMU
+can be launched with:
+
+.. parsed-literal::
+
+   |qemu_system| [...OPTIONS...] -vnc :1,sasl -monitor stdio
+
+.. _vnc_005fsec_005fcertificate_005fsasl:
+
+With x509 certificates and SASL authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the desired SASL authentication mechanism does not supported SSF
+layers, then it is strongly advised to run it in combination with TLS
+and x509 certificates. This provides securely encrypted data stream,
+avoiding risk of compromising of the security credentials. This can be
+enabled, by combining the 'sasl' option with the aforementioned TLS +
+x509 options:
+
+.. parsed-literal::
+
+   |qemu_system| [...OPTIONS...] \
+     -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
+     -vnc :1,tls-creds=tls0,sasl -monitor stdio
+
+.. _vnc_005fsetup_005fsasl:
+
+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
+
+::
+
+   mech_list: gssapi
+   keytab: /etc/qemu/krb5.tab
+
+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
+
+::
+
+   mech_list: scram-sha-1
+   sasldb_path: /etc/qemu/passwd.db
+
+The ``saslpasswd2`` program can be used to populate the ``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.