[PATCH 1/6] docs/drvqemu: Convert to RST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



There are two links to this document using anchors so they need to be
updated as well.

Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 docs/drvqemu.html.in            | 743 --------------------------------
 docs/drvqemu.rst                | 588 +++++++++++++++++++++++++
 docs/formatdomain.rst           |   2 +-
 docs/manpages/virt-qemu-run.rst |   2 +-
 docs/meson.build                |   2 +-
 5 files changed, 591 insertions(+), 746 deletions(-)
 delete mode 100644 docs/drvqemu.html.in
 create mode 100644 docs/drvqemu.rst

diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in
deleted file mode 100644
index fdf74979ad..0000000000
--- a/docs/drvqemu.html.in
+++ /dev/null
@@ -1,743 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml";>
-  <body>
-    <h1>KVM/QEMU hypervisor driver</h1>
-
-    <ul id="toc"></ul>
-
-    <p>
-      The libvirt KVM/QEMU driver can manage any QEMU emulator from
-      version 1.5.0 or later.
-    </p>
-
-    <h2><a id="project">Project Links</a></h2>
-
-    <ul>
-      <li>
-        The <a href="https://www.linux-kvm.org/";>KVM</a> Linux
-        hypervisor
-      </li>
-      <li>
-        The <a href="https://wiki.qemu.org/Index.html";>QEMU</a> emulator
-      </li>
-    </ul>
-
-    <h2><a id="prereq">Deployment pre-requisites</a></h2>
-
-    <ul>
-      <li>
-        <strong>QEMU emulators</strong>: The driver will probe <code>/usr/bin</code>
-        for the presence of <code>qemu</code>, <code>qemu-system-x86_64</code>,
-        <code>qemu-system-microblaze</code>,
-        <code>qemu-system-microblazeel</code>,
-        <code>qemu-system-mips</code>,<code>qemu-system-mipsel</code>,
-        <code>qemu-system-sparc</code>,<code>qemu-system-ppc</code>. The results
-        of this can be seen from the capabilities XML output.
-      </li>
-      <li>
-        <strong>KVM hypervisor</strong>: The driver will probe <code>/usr/bin</code>
-        for the presence of <code>qemu-kvm</code> and <code>/dev/kvm</code> device
-        node. If both are found, then KVM fully virtualized, hardware accelerated
-        guests will be available.
-      </li>
-    </ul>
-
-    <h2><a id="uris">Connections to QEMU driver</a></h2>
-
-    <p>
-    The libvirt QEMU driver is a multi-instance driver, providing a single
-    system wide privileged driver (the "system" instance), and per-user
-    unprivileged drivers (the "session" instance). The URI driver protocol
-    is "qemu". Some example connection URIs for the libvirt driver are:
-    </p>
-
-<pre>
-qemu:///session                      (local access to per-user instance)
-qemu+unix:///session                 (local access to per-user instance)
-
-qemu:///system                       (local access to system instance)
-qemu+unix:///system                  (local access to system instance)
-qemu://example.com/system            (remote access, TLS/x509)
-qemu+tcp://example.com/system        (remote access, SASl/Kerberos)
-qemu+ssh://root@xxxxxxxxxxx/system   (remote access, SSH tunnelled)
-</pre>
-
-    <h3><a id="uriembedded">Embedded driver</a></h3>
-
-    <p>
-      Since 6.1.0 the QEMU driver has experimental support for operating
-      in an embedded mode. In this scenario, rather than connecting to
-      the libvirtd daemon, the QEMU driver runs in the client application
-      process directly. To use this the client application must have
-      registered &amp; be running an instance of the event loop. To open
-      the driver in embedded mode the app use the new URI path and specify
-      a virtual root directory under which the driver will create content.
-      The path to the root directory must be absolute. Passing a relative
-      path results in an error.
-    </p>
-
-    <pre>
-      qemu:///embed?root=/some/dir
-    </pre>
-
-    <p>
-      Broadly speaking the range of functionality is intended to be
-      on a par with that seen when using the traditional system or
-      session libvirt connections to QEMU. The features will of course
-      differ depending on whether the application using the embedded
-      driver is running privileged or unprivileged. For example PCI
-      device assignment or TAP based networking are only available
-      when running privileged. While the embedded mode is still classed
-      as experimental some features may change their default settings
-      between releases.
-    </p>
-
-    <p>
-      By default if the application uses any APIs associated with
-      secondary drivers, these will result in a connection being
-      opened to the corresponding driver in libvirtd. For example,
-      this allows a virtual machine from the embedded QEMU to connect
-      its NIC to a virtual network or connect its disk to a storage
-      volume. Some of the secondary drivers will also be able to support
-      running in embedded mode. Currently this is supported by the
-      secrets driver, to allow for use of VMs with encrypted disks
-    </p>
-
-    <h4><a id="embedTree">Directory tree</a></h4>
-
-    <p>
-      Under the specified root directory the following locations will
-      be used
-    </p>
-
-    <pre>
-/some/dir
-  |
-  +- log
-  |   |
-  |   +- qemu
-  |   +- swtpm
-  |
-  +- etc
-  |   |
-  |   +- qemu
-  |   +- pki
-  |       |
-  |       +- qemu
-  |
-  +- run
-  |   |
-  |   +- qemu
-  |   +- swtpm
-  |
-  +- cache
-  |   |
-  |   +- qemu
-  |
-  +- lib
-      |
-      +- qemu
-      +- swtpm
-    </pre>
-
-    <p>
-      Note that UNIX domain sockets used for QEMU virtual machines had
-      a maximum filename length of 108 characters. Bear this in mind
-      when picking a root directory to avoid risk of exhausting the
-      filename space. The application is responsible for recursively
-      purging the contents of this directory tree once they no longer
-      require a connection, though it can also be left intact for reuse
-      when opening a future connection.
-    </p>
-
-    <h4><a id="embedAPI">API usage with event loop</a></h4>
-
-    <p>
-      To use the QEMU driver in embedded mode the application must
-      register an event loop with libvirt. Many of the QEMU driver
-      API calls will rely on the event loop processing data. With this
-      in mind, applications must <strong>NEVER</strong> invoke API
-      calls from the event loop thread itself, only other threads.
-      Not following this rule will lead to deadlocks in the API.
-      This restriction was lifted starting from 6.2.0 release, when
-      QMP processing moved to a dedicated thread. However, it is
-      important to let the event loop run after each API call, even
-      the ones made from the event loop thread itself.
-    </p>
-
-    <h2><a id="configFiles">Location of configuration files</a></h2>
-
-    <p>
-      The QEMU driver comes with sane default values. However, during its
-      initialization it reads a configuration file which offers system
-      administrator or an user to override some of that default. The location
-      of the file depends on the connection URI, as follows:
-    </p>
-
-    <table>
-      <tr>
-        <td><code>qemu:///system</code></td>
-        <td><code>/etc/libvirt/qemu.conf</code></td>
-      </tr>
-      <tr>
-        <td><code>qemu:///session</code></td>
-        <td><code>$XDG_CONFIG_HOME/libvirt/qemu.conf</code></td>
-      </tr>
-      <tr>
-        <td><code>qemu:///embed</code></td>
-        <td><code>$rootdir/etc/qemu.conf</code></td>
-      </tr>
-    </table>
-
-    <p>
-      If <code>$XDG_CONFIG_HOME</code> is not set in the environment, it
-      defaults to <code>$HOME/.config</code>. For the embed URI the
-      <code>$rootdir</code> represents the specified root directory from
-      the connection URI.
-    </p>
-
-    <p>
-      Please note, that it is very likely that the only qemu.conf file that
-      will exist after installing libvirt is the
-      <code>/etc/libvirt/qemu.conf</code>, if users of the session daemon or
-      the embed driver want to override a built in value, then they need to
-      create the file before connecting to the respective URI.
-    </p>
-
-    <h2><a id="security">Driver security architecture</a></h2>
-
-    <p>
-      There are multiple layers to security in the QEMU driver, allowing for
-      flexibility in the use of QEMU based virtual machines.
-    </p>
-
-    <h3><a id="securitydriver">Driver instances</a></h3>
-
-    <p>
-      As explained above there are two ways to access the QEMU driver
-      in libvirt. The "qemu:///session" family of URIs connect to a
-      libvirtd instance running as the same user/group ID as the client
-      application. Thus the QEMU instances spawned from this driver will
-      share the same privileges as the client application. The intended
-      use case for this driver is desktop virtualization, with virtual
-      machines storing their disk images in the user's home directory and
-      being managed from the local desktop login session.
-    </p>
-
-    <p>
-      The "qemu:///system" family of URIs connect to a
-      libvirtd instance running as the privileged system account 'root'.
-      Thus the QEMU instances spawned from this driver may have much
-      higher privileges than the client application managing them.
-      The intended use case for this driver is server virtualization,
-      where the virtual machines may need to be connected to host
-      resources (block, PCI, USB, network devices) whose access requires
-      elevated privileges.
-    </p>
-
-    <h3><a id="securitydac">POSIX users/groups</a></h3>
-
-    <p>
-      In the "session" instance, the POSIX users/groups model restricts QEMU
-      virtual machines (and libvirtd in general) to only have access to resources
-      with the same user/group ID as the client application. There is no
-      finer level of configuration possible for the "session" instances.
-    </p>
-
-    <p>
-      In the "system" instance, libvirt releases from 0.7.0 onwards allow
-      control over the user/group that the QEMU virtual machines are run
-      as. A build of libvirt with no configuration parameters set will
-      still run QEMU processes as root:root. It is possible to change
-      this default by using the --with-qemu-user=$USERNAME and
-      --with-qemu-group=$GROUPNAME arguments to 'configure' during
-      build. It is strongly recommended that vendors build with both
-      of these arguments set to 'qemu'. Regardless of this build time
-      default, administrators can set a per-host default setting in
-      the <code>/etc/libvirt/qemu.conf</code> configuration file via
-      the <code>user=$USERNAME</code> and <code>group=$GROUPNAME</code>
-      parameters. When a non-root user or group is configured, the
-      libvirt QEMU driver will change uid/gid to match immediately
-      before executing the QEMU binary for a virtual machine.
-    </p>
-
-    <p>
-      If QEMU virtual machines from the "system" instance are being
-      run as non-root, there will be greater restrictions on what
-      host resources the QEMU process will be able to access. The
-      libvirtd daemon will attempt to manage permissions on resources
-      to minimise the likelihood of unintentional security denials,
-      but the administrator / application developer must be aware of
-      some of the consequences / restrictions.
-    </p>
-
-    <ul>
-      <li>
-        <p>
-          The directories <code>/var/run/libvirt/qemu/</code>,
-          <code>/var/lib/libvirt/qemu/</code> and
-          <code>/var/cache/libvirt/qemu/</code> must all have their
-          ownership set to match the user / group ID that QEMU
-          guests will be run as. If the vendor has set a non-root
-          user/group for the QEMU driver at build time, the
-          permissions should be set automatically at install time.
-          If a host administrator customizes user/group in
-          <code>/etc/libvirt/qemu.conf</code>, they will need to
-          manually set the ownership on these directories.
-        </p>
-      </li>
-      <li>
-        <p>
-          When attaching USB and PCI devices to a QEMU guest,
-          QEMU will need to access files in <code>/dev/bus/usb</code>
-          and <code>/sys/bus/pci/devices</code> respectively. The libvirtd daemon
-          will automatically set the ownership on specific devices
-          that are assigned to a guest at start time. There should
-          not be any need for administrator changes in this respect.
-        </p>
-      </li>
-      <li>
-        <p>
-          Any files/devices used as guest disk images must be
-          accessible to the user/group ID that QEMU guests are
-          configured to run as. The libvirtd daemon will automatically
-          set the ownership of the file/device path to the correct
-          user/group ID. Applications / administrators must be aware
-          though that the parent directory permissions may still
-          deny access. The directories containing disk images
-          must either have their ownership set to match the user/group
-          configured for QEMU, or their UNIX file permissions must
-          have the 'execute/search' bit enabled for 'others'.
-        </p>
-        <p>
-          The simplest option is the latter one, of just enabling
-          the 'execute/search' bit. For any directory to be used
-          for storing disk images, this can be achieved by running
-          the following command on the directory itself, and any
-          parent directories
-        </p>
-<pre>
-chmod o+x /path/to/directory
-</pre>
-        <p>
-          In particular note that if using the "system" instance
-          and attempting to store disk images in a user home
-          directory, the default permissions on $HOME are typically
-          too restrictive to allow access.
-        </p>
-      </li>
-    </ul>
-
-    <p>
-      The libvirt maintainers <strong>strongly recommend against</strong>
-      running QEMU as the root user/group. This should not be required
-      in most supported usage scenarios, as libvirt will generally do the
-      right thing to grant QEMU access to files it is permitted to
-      use when it is running non-root.
-    </p>
-
-    <h3><a id="securitycap">Linux process capabilities</a></h3>
-
-    <p>
-      In versions of libvirt prior to 6.0.0, even if QEMU was configured
-      to run as the root user / group, libvirt would strip all process
-      capabilities. This meant that QEMU could only read/write files
-      owned by root, or with open permissions. In reality, stripping
-      capabilities did not have any security benefit, as it was trivial
-      to get commands to run in another context with full capabilities,
-      for example, by creating a cronjob.
-    </p>
-    <p>
-      Thus since 6.0.0, if QEMU is running as root, it will keep all
-      process capabilities. Behaviour when QEMU is running non-root
-      is unchanged, it still has no capabilities.
-    </p>
-
-    <h3><a id="securityselinux">SELinux basic confinement</a></h3>
-
-    <p>
-      The basic SELinux protection for QEMU virtual machines is intended to
-      protect the host OS from a compromised virtual machine process. There
-      is no protection between guests.
-    </p>
-
-    <p>
-      In the basic model, all QEMU virtual machines run under the confined
-      domain <code>root:system_r:qemu_t</code>. It is required that any
-      disk image assigned to a QEMU virtual machine is labelled with
-      <code>system_u:object_r:virt_image_t</code>. In a default deployment,
-      package vendors/distributor will typically ensure that the directory
-      <code>/var/lib/libvirt/images</code> has this label, such that any
-      disk images created in this directory will automatically inherit the
-      correct labelling. If attempting to use disk images in another
-      location, the user/administrator must ensure the directory has be
-      given this requisite label. Likewise physical block devices must
-      be labelled <code>system_u:object_r:virt_image_t</code>.
-    </p>
-    <p>
-      Not all filesystems allow for labelling of individual files. In
-      particular NFS, VFat and NTFS have no support for labelling. In
-      these cases administrators must use the 'context' option when
-      mounting the filesystem to set the default label to
-      <code>system_u:object_r:virt_image_t</code>. In the case of
-      NFS, there is an alternative option, of enabling the <code>virt_use_nfs</code>
-      SELinux boolean.
-    </p>
-
-    <h3><a id="securitysvirt">SELinux sVirt confinement</a></h3>
-
-    <p>
-      The SELinux sVirt protection for QEMU virtual machines builds to the
-      basic level of protection, to also allow individual guests to be
-      protected from each other.
-    </p>
-
-    <p>
-      In the sVirt model, each QEMU virtual machine runs under its own
-      confined domain, which is based on <code>system_u:system_r:svirt_t:s0</code>
-      with a unique category appended, eg, <code>system_u:system_r:svirt_t:s0:c34,c44</code>.
-      The rules are setup such that a domain can only access files which are
-      labelled with the matching category level, eg
-      <code>system_u:object_r:svirt_image_t:s0:c34,c44</code>. This prevents one
-      QEMU process accessing any file resources that are prevent to another QEMU
-      process.
-    </p>
-
-    <p>
-      There are two ways of assigning labels to virtual machines under sVirt.
-      In the default setup, if sVirt is enabled, guests will get an automatically
-      assigned unique label each time they are booted. The libvirtd daemon will
-      also automatically relabel exclusive access disk images to match this
-      label.  Disks that are marked as &lt;shared&gt; will get a generic
-      label <code>system_u:system_r:svirt_image_t:s0</code> allowing all guests
-      read/write access them, while disks marked as &lt;readonly&gt; will
-      get a generic label <code>system_u:system_r:svirt_content_t:s0</code>
-      which allows all guests read-only access.
-    </p>
-
-    <p>
-      With statically assigned labels, the application should include the
-      desired guest and file labels in the XML at time of creating the
-      guest with libvirt. In this scenario the application is responsible
-      for ensuring the disk images &amp; similar resources are suitably
-      labelled to match, libvirtd will not attempt any relabelling.
-    </p>
-
-    <p>
-      If the sVirt security model is active, then the node capabilities
-      XML will include its details. If a virtual machine is currently
-      protected by the security model, then the guest XML will include
-      its assigned labels. If enabled at compile time, the sVirt security
-      model will always be activated if SELinux is available on the host
-      OS. To disable sVirt, and revert to the basic level of SELinux
-      protection (host protection only), the <code>/etc/libvirt/qemu.conf</code>
-      file can be used to change the setting to <code>security_driver="none"</code>
-    </p>
-
-    <h3><a id="securitysvirtaa">AppArmor sVirt confinement</a></h3>
-
-    <p>
-      When using basic AppArmor protection for the libvirtd daemon and
-      QEMU virtual machines, the intention is to protect the host OS
-      from a compromised virtual machine process. There is no protection
-      between guests.
-    </p>
-
-    <p>
-      The AppArmor sVirt protection for QEMU virtual machines builds on
-      this basic level of protection, to also allow individual guests to
-      be protected from each other.
-    </p>
-
-    <p>
-      In the sVirt model, if a profile is loaded for the libvirtd daemon,
-      then each <code>qemu:///system</code> QEMU virtual machine will have
-      a profile created for it when the virtual machine is started if one
-      does not already exist. This generated profile uses a profile name
-      based on the UUID of the QEMU virtual machine and contains rules
-      allowing access to only the files it needs to run, such as its disks,
-      pid file and log files. Just before the QEMU virtual machine is
-      started, the libvirtd daemon will change into this unique profile,
-      preventing the QEMU process from accessing any file resources that
-      are present in another QEMU process or the host machine.
-    </p>
-
-    <p>
-      The AppArmor sVirt implementation is flexible in that it allows an
-      administrator to customize the template file in
-      <code>/etc/apparmor.d/libvirt/TEMPLATE</code> for site-specific
-      access for all newly created QEMU virtual machines. Also, when a new
-      profile is generated, two files are created:
-      <code>/etc/apparmor.d/libvirt/libvirt-&lt;uuid&gt;</code> and
-      <code>/etc/apparmor.d/libvirt/libvirt-&lt;uuid&gt;.files</code>. The
-      former can be fine-tuned by the administrator to allow custom access
-      for this particular QEMU virtual machine, and the latter will be
-      updated appropriately when required file access changes, such as when
-      a disk is added. This flexibility allows for situations such as
-      having one virtual machine in complain mode with all others in
-      enforce mode.
-    </p>
-
-    <p>
-      While users can define their own AppArmor profile scheme, a typical
-      configuration will include a profile for <code>/usr/sbin/libvirtd</code>,
-      <code>/usr/lib/libvirt/virt-aa-helper</code> or
-      <code>/usr/libexec/virt-aa-helper</code>(a helper program which the
-      libvirtd daemon uses instead of manipulating AppArmor directly), and
-      an abstraction to be included by <code>/etc/apparmor.d/libvirt/TEMPLATE</code>
-      (typically <code>/etc/apparmor.d/abstractions/libvirt-qemu</code>).
-      An example profile scheme can be found in the examples/apparmor
-      directory of the source distribution.
-    </p>
-
-    <p>
-      If the sVirt security model is active, then the node capabilities
-      XML will include its details. If a virtual machine is currently
-      protected by the security model, then the guest XML will include
-      its assigned profile name. If enabled at compile time, the sVirt
-      security model will be activated if AppArmor is available on the host
-      OS and a profile for the libvirtd daemon is loaded when libvirtd is
-      started. To disable sVirt, and revert to the basic level of AppArmor
-      protection (host protection only), the <code>/etc/libvirt/qemu.conf</code>
-      file can be used to change the setting to <code>security_driver="none"</code>.
-    </p>
-
-
-    <h3><a id="securityacl">Cgroups device ACLs</a></h3>
-
-    <p>
-      Linux kernels have a capability known as "cgroups" which is used
-      for resource management. It is implemented via a number of "controllers",
-      each controller covering a specific task/functional area. One of the
-      available controllers is the "devices" controller, which is able to
-      setup access control lists of block/character devices that a cgroup
-      should be allowed to access. If the "devices" controller is mounted on a
-      host, then libvirt will automatically create a dedicated cgroup for each
-      QEMU virtual machine and setup the device access control list so that the
-      QEMU process can only access shared devices, and explicitly assigned disks
-      images backed by block devices.
-    </p>
-
-    <p>
-      The list of shared devices a guest is allowed access to is
-    </p>
-
-<pre>
-/dev/null, /dev/full, /dev/zero,
-/dev/random, /dev/urandom,
-/dev/ptmx, /dev/kvm,
-</pre>
-
-    <p>
-      In the event of unanticipated needs arising, this can be customized
-      via the <code>/etc/libvirt/qemu.conf</code> file.
-      To mount the cgroups device controller, the following command
-      should be run as root, prior to starting libvirtd
-    </p>
-
-<pre>
-mkdir /dev/cgroup
-mount -t cgroup none /dev/cgroup -o devices
-</pre>
-
-    <p>
-      libvirt will then place each virtual machine in a cgroup at
-      <code>/dev/cgroup/libvirt/qemu/$VMNAME/</code>
-    </p>
-
-    <h2><a id="imex">Import and export of libvirt domain XML configs</a></h2>
-
-    <p>The QEMU driver currently supports a single native
-      config format known as <code>qemu-argv</code>. The data for this format
-      is expected to be a single line first a list of environment variables,
-      then the QEMu binary name, finally followed by the QEMU command line
-      arguments</p>
-
-    <h3><a id="xmlimport">Converting from QEMU args to domain XML</a></h3>
-
-    <p>
-      <b>Note:</b> this operation is <span class="removed"> deleted as of
-        5.5.0</span> and will return an error.
-    </p>
-    <p>
-      The <code>virsh domxml-from-native</code> provides a way to
-      convert an existing set of QEMU args into a guest description
-      using libvirt Domain XML that can then be used by libvirt.
-      Please note that this command is intended to be used to convert
-      existing qemu guests previously started from the command line to
-      be managed through libvirt.  It should not be used a method of
-      creating new guests from scratch.  New guests should be created
-      using an application calling the libvirt APIs (see
-      the <a href="apps.html">libvirt applications page</a> for some
-      examples) or by manually crafting XML to pass to virsh.
-    </p>
-
-    <h3><a id="xmlexport">Converting from domain XML to QEMU args</a></h3>
-
-    <p>
-      The <code>virsh domxml-to-native</code> provides a way to convert a
-      guest description using libvirt Domain XML, into a set of QEMU args
-      that can be run manually. Note that currently the command line formatted
-      by libvirt is no longer suited for manually running qemu as the
-      configuration expects various resources and open file descriptors passed
-      to the process which are usually prepared by libvirtd.
-    </p>
-
-    <h2><a id="qemucommand">Pass-through of arbitrary qemu
-    commands</a></h2>
-
-    <p>Libvirt provides an XML namespace and an optional
-      library <code>libvirt-qemu.so</code> for dealing specifically
-      with qemu.  When used correctly, these extensions allow testing
-      specific qemu features that have not yet been ported to the
-      generic libvirt XML and API interfaces.  However, they
-      are <b>unsupported</b>, in that the library is not guaranteed to
-      have a stable API, abusing the library or XML may result in
-      inconsistent state the crashes libvirtd, and upgrading either
-      qemu-kvm or libvirtd may break behavior of a domain that was
-      relying on a qemu-specific pass-through.  If you find yourself
-      needing to use them to access a particular qemu feature, then
-      please post an RFE to the libvirt mailing list to get that
-      feature incorporated into the stable libvirt XML and API
-      interfaces.
-    </p>
-    <p>The library provides two
-      API: <code>virDomainQemuMonitorCommand</code>, for sending an
-      arbitrary monitor command (in either HMP or QMP format) to a
-      qemu guest (<span class="since">Since 0.8.3</span>),
-      and <code>virDomainQemuAttach</code>, for registering a qemu
-      domain that was manually started so that it can then be managed
-      by libvirtd (<span class="since">Since 0.9.4</span>,
-      <span class="removed">removed as of 5.5.0</span>).
-    </p>
-    <p>Additionally, the following XML additions allow fine-tuning of
-      the command line given to qemu when starting a domain
-      (<span class="since">Since 0.8.3</span>).  In order to use the
-      XML additions, it is necessary to issue an XML namespace request
-      (the special <code>xmlns:<i>name</i></code> attribute) that
-      pulls in <code>http://libvirt.org/schemas/domain/qemu/1.0</code>;
-      typically, the namespace is given the name
-      of <code>qemu</code>.  With the namespace in place, it is then
-      possible to add an element <code>&lt;qemu:commandline&gt;</code>
-      under <code>domain</code>, with the following sub-elements
-      repeated as often as needed:
-    </p>
-      <dl>
-        <dt><code>qemu:arg</code></dt>
-        <dd>Add an additional command-line argument to the qemu
-          process when starting the domain, given by the value of the
-          attribute <code>value</code>.
-        </dd>
-        <dt><code>qemu:env</code></dt>
-        <dd>Add an additional environment variable to the qemu
-          process when starting the domain, given with the name-value
-          pair recorded in the attributes <code>name</code>
-          and optional <code>value</code>.</dd>
-      </dl>
-      <p>Example:</p><pre>
-&lt;domain type='qemu' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'&gt;
-  &lt;name&gt;QEMU-fedora-i686&lt;/name&gt;
-  &lt;memory&gt;219200&lt;/memory&gt;
-  &lt;os&gt;
-    &lt;type arch='i686' machine='pc'&gt;hvm&lt;/type&gt;
-  &lt;/os&gt;
-  &lt;devices&gt;
-    &lt;emulator&gt;/usr/bin/qemu-system-x86_64&lt;/emulator&gt;
-  &lt;/devices&gt;
-  &lt;qemu:commandline&gt;
-    &lt;qemu:arg value='-newarg'/&gt;
-    &lt;qemu:env name='QEMU_ENV' value='VAL'/&gt;
-  &lt;/qemu:commandline&gt;
-&lt;/domain&gt;
-</pre>
-
-    <h2><a id="xmlnsfeatures">QEMU feature configuration for testing</a></h2>
-
-      <p>
-        In some cases e.g. when developing a new feature or for testing it may
-        be required to control a given qemu feature (or qemu capability) to test
-        it before it's complete or disable it for debugging purposes.
-        <span class="since">Since 5.5.0</span> it's possible to use the same
-        special qemu namespace as above
-        (<code>http://libvirt.org/schemas/domain/qemu/1.0</code>) and use
-        <code>&lt;qemu:capabilities&gt;</code> element to add
-        (<code>&lt;qemu:add capability="capname"/&gt;</code>) or remove
-        (<code>&lt;qemu:del capability="capname"/&gt;</code>) capability bits.
-        The naming of the feature bits is the same libvirt uses in the status
-        XML. Note that this feature is meant for experiments only and should
-        _not_ be used in production.
-      </p>
-
-      <p>Example:</p><pre>
-&lt;domain type='qemu' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'&gt;
-  &lt;name&gt;testvm&lt;/name&gt;
-
-   [...]
-
-  &lt;qemu:capabilities&gt;
-    &lt;qemu:add capability='blockdev'/&gt;
-    &lt;qemu:del capability='drive'/&gt;
-  &lt;/qemu:capabilities&gt;
-&lt;/domain&gt;
-</pre>
-
-    <h2><a id="xmlconfig">Example domain XML config</a></h2>
-
-    <h3>QEMU emulated guest on x86_64</h3>
-
-        <pre>&lt;domain type='qemu'&gt;
-  &lt;name&gt;QEMU-fedora-i686&lt;/name&gt;
-  &lt;uuid&gt;c7a5fdbd-cdaf-9455-926a-d65c16db1809&lt;/uuid&gt;
-  &lt;memory&gt;219200&lt;/memory&gt;
-  &lt;currentMemory&gt;219200&lt;/currentMemory&gt;
-  &lt;vcpu&gt;2&lt;/vcpu&gt;
-  &lt;os&gt;
-    &lt;type arch='i686' machine='pc'&gt;hvm&lt;/type&gt;
-    &lt;boot dev='cdrom'/&gt;
-  &lt;/os&gt;
-  &lt;devices&gt;
-    &lt;emulator&gt;/usr/bin/qemu-system-x86_64&lt;/emulator&gt;
-    &lt;disk type='file' device='cdrom'&gt;
-      &lt;source file='/home/user/boot.iso'/&gt;
-      &lt;target dev='hdc'/&gt;
-      &lt;readonly/&gt;
-    &lt;/disk&gt;
-    &lt;disk type='file' device='disk'&gt;
-      &lt;source file='/home/user/fedora.img'/&gt;
-      &lt;target dev='hda'/&gt;
-    &lt;/disk&gt;
-    &lt;interface type='network'&gt;
-      &lt;source network='default'/&gt;
-    &lt;/interface&gt;
-    &lt;graphics type='vnc' port='-1'/&gt;
-  &lt;/devices&gt;
-&lt;/domain&gt;</pre>
-
-    <h3>KVM hardware accelerated guest on i686</h3>
-
-        <pre>&lt;domain type='kvm'&gt;
-  &lt;name&gt;demo2&lt;/name&gt;
-  &lt;uuid&gt;4dea24b3-1d52-d8f3-2516-782e98a23fa0&lt;/uuid&gt;
-  &lt;memory&gt;131072&lt;/memory&gt;
-  &lt;vcpu&gt;1&lt;/vcpu&gt;
-  &lt;os&gt;
-    &lt;type arch="i686"&gt;hvm&lt;/type&gt;
-  &lt;/os&gt;
-  &lt;clock sync="localtime"/&gt;
-  &lt;devices&gt;
-    &lt;emulator&gt;/usr/bin/qemu-kvm&lt;/emulator&gt;
-    &lt;disk type='file' device='disk'&gt;
-      &lt;source file='/var/lib/libvirt/images/demo2.img'/&gt;
-      &lt;target dev='hda'/&gt;
-    &lt;/disk&gt;
-    &lt;interface type='network'&gt;
-      &lt;source network='default'/&gt;
-      &lt;mac address='24:42:53:21:52:45'/&gt;
-    &lt;/interface&gt;
-    &lt;graphics type='vnc' port='-1' keymap='de'/&gt;
-  &lt;/devices&gt;
-&lt;/domain&gt;</pre>
-
-  </body>
-</html>
diff --git a/docs/drvqemu.rst b/docs/drvqemu.rst
new file mode 100644
index 0000000000..0f8fd9e47d
--- /dev/null
+++ b/docs/drvqemu.rst
@@ -0,0 +1,588 @@
+.. role:: since
+.. role:: removed
+
+==========================
+KVM/QEMU hypervisor driver
+==========================
+
+The libvirt KVM/QEMU driver can manage any QEMU emulator from version 1.5.0 or
+later.
+
+.. contents::
+
+Project Links
+-------------
+
+-  The `KVM <https://www.linux-kvm.org/>`__ Linux hypervisor
+-  The `QEMU <https://wiki.qemu.org/Index.html>`__ emulator
+
+Deployment pre-requisites
+-------------------------
+
+-  **QEMU emulators**: The driver will probe ``/usr/bin`` for the presence of
+   ``qemu``, ``qemu-system-x86_64``, ``qemu-system-microblaze``,
+   ``qemu-system-microblazeel``, ``qemu-system-mips``,\ ``qemu-system-mipsel``,
+   ``qemu-system-sparc``,\ ``qemu-system-ppc``. The results of this can be seen
+   from the capabilities XML output.
+-  **KVM hypervisor**: The driver will probe ``/usr/bin`` for the presence of
+   ``qemu-kvm`` and ``/dev/kvm`` device node. If both are found, then KVM fully
+   virtualized, hardware accelerated guests will be available.
+
+Connections to QEMU driver
+--------------------------
+
+The libvirt QEMU driver is a multi-instance driver, providing a single system
+wide privileged driver (the "system" instance), and per-user unprivileged
+drivers (the "session" instance). The URI driver protocol is "qemu". Some
+example connection URIs for the libvirt driver are:
+
+::
+
+   qemu:///session                      (local access to per-user instance)
+   qemu+unix:///session                 (local access to per-user instance)
+
+   qemu:///system                       (local access to system instance)
+   qemu+unix:///system                  (local access to system instance)
+   qemu://example.com/system            (remote access, TLS/x509)
+   qemu+tcp://example.com/system        (remote access, SASl/Kerberos)
+   qemu+ssh://root@xxxxxxxxxxx/system   (remote access, SSH tunnelled)
+
+Embedded driver
+~~~~~~~~~~~~~~~
+
+Since 6.1.0 the QEMU driver has experimental support for operating in an
+embedded mode. In this scenario, rather than connecting to the libvirtd daemon,
+the QEMU driver runs in the client application process directly. To use this the
+client application must have registered & be running an instance of the event
+loop. To open the driver in embedded mode the app use the new URI path and
+specify a virtual root directory under which the driver will create content. The
+path to the root directory must be absolute. Passing a relative path results in
+an error.
+
+::
+
+         qemu:///embed?root=/some/dir
+
+Broadly speaking the range of functionality is intended to be on a par with that
+seen when using the traditional system or session libvirt connections to QEMU.
+The features will of course differ depending on whether the application using
+the embedded driver is running privileged or unprivileged. For example PCI
+device assignment or TAP based networking are only available when running
+privileged. While the embedded mode is still classed as experimental some
+features may change their default settings between releases.
+
+By default if the application uses any APIs associated with secondary drivers,
+these will result in a connection being opened to the corresponding driver in
+libvirtd. For example, this allows a virtual machine from the embedded QEMU to
+connect its NIC to a virtual network or connect its disk to a storage volume.
+Some of the secondary drivers will also be able to support running in embedded
+mode. Currently this is supported by the secrets driver, to allow for use of VMs
+with encrypted disks
+
+Directory tree
+^^^^^^^^^^^^^^
+
+Under the specified root directory the following locations will be used
+
+::
+
+   /some/dir
+     |
+     +- log
+     |   |
+     |   +- qemu
+     |   +- swtpm
+     |
+     +- etc
+     |   |
+     |   +- qemu
+     |   +- pki
+     |       |
+     |       +- qemu
+     |
+     +- run
+     |   |
+     |   +- qemu
+     |   +- swtpm
+     |
+     +- cache
+     |   |
+     |   +- qemu
+     |
+     +- lib
+         |
+         +- qemu
+         +- swtpm
+
+Note that UNIX domain sockets used for QEMU virtual machines had a maximum
+filename length of 108 characters. Bear this in mind when picking a root
+directory to avoid risk of exhausting the filename space. The application is
+responsible for recursively purging the contents of this directory tree once
+they no longer require a connection, though it can also be left intact for reuse
+when opening a future connection.
+
+API usage with event loop
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use the QEMU driver in embedded mode the application must register an event
+loop with libvirt. Many of the QEMU driver API calls will rely on the event loop
+processing data. With this in mind, applications must **NEVER** invoke API calls
+from the event loop thread itself, only other threads. Not following this rule
+will lead to deadlocks in the API. This restriction was lifted starting from
+6.2.0 release, when QMP processing moved to a dedicated thread. However, it is
+important to let the event loop run after each API call, even the ones made from
+the event loop thread itself.
+
+Location of configuration files
+-------------------------------
+
+The QEMU driver comes with sane default values. However, during its
+initialization it reads a configuration file which offers system administrator
+or an user to override some of that default. The location of the file depends on
+the connection URI, as follows:
+
+=================== ======================================
+``qemu:///system``  ``/etc/libvirt/qemu.conf``
+``qemu:///session`` ``$XDG_CONFIG_HOME/libvirt/qemu.conf``
+``qemu:///embed``   ``$rootdir/etc/qemu.conf``
+=================== ======================================
+
+If ``$XDG_CONFIG_HOME`` is not set in the environment, it defaults to
+``$HOME/.config``. For the embed URI the ``$rootdir`` represents the specified
+root directory from the connection URI.
+
+Please note, that it is very likely that the only qemu.conf file that will exist
+after installing libvirt is the ``/etc/libvirt/qemu.conf``, if users of the
+session daemon or the embed driver want to override a built in value, then they
+need to create the file before connecting to the respective URI.
+
+Driver security architecture
+----------------------------
+
+There are multiple layers to security in the QEMU driver, allowing for
+flexibility in the use of QEMU based virtual machines.
+
+Driver instances
+~~~~~~~~~~~~~~~~
+
+As explained above there are two ways to access the QEMU driver in libvirt. The
+"qemu:///session" family of URIs connect to a libvirtd instance running as the
+same user/group ID as the client application. Thus the QEMU instances spawned
+from this driver will share the same privileges as the client application. The
+intended use case for this driver is desktop virtualization, with virtual
+machines storing their disk images in the user's home directory and being
+managed from the local desktop login session.
+
+The "qemu:///system" family of URIs connect to a libvirtd instance running as
+the privileged system account 'root'. Thus the QEMU instances spawned from this
+driver may have much higher privileges than the client application managing
+them. The intended use case for this driver is server virtualization, where the
+virtual machines may need to be connected to host resources (block, PCI, USB,
+network devices) whose access requires elevated privileges.
+
+POSIX users/groups
+~~~~~~~~~~~~~~~~~~
+
+In the "session" instance, the POSIX users/groups model restricts QEMU virtual
+machines (and libvirtd in general) to only have access to resources with the
+same user/group ID as the client application. There is no finer level of
+configuration possible for the "session" instances.
+
+In the "system" instance, libvirt releases from 0.7.0 onwards allow control over
+the user/group that the QEMU virtual machines are run as. A build of libvirt
+with no configuration parameters set will still run QEMU processes as root:root.
+It is possible to change this default by using the --with-qemu-user=$USERNAME
+and --with-qemu-group=$GROUPNAME arguments to 'configure' during build. It is
+strongly recommended that vendors build with both of these arguments set to
+'qemu'. Regardless of this build time default, administrators can set a per-host
+default setting in the ``/etc/libvirt/qemu.conf`` configuration file via the
+``user=$USERNAME`` and ``group=$GROUPNAME`` parameters. When a non-root user or
+group is configured, the libvirt QEMU driver will change uid/gid to match
+immediately before executing the QEMU binary for a virtual machine.
+
+If QEMU virtual machines from the "system" instance are being run as non-root,
+there will be greater restrictions on what host resources the QEMU process will
+be able to access. The libvirtd daemon will attempt to manage permissions on
+resources to minimise the likelihood of unintentional security denials, but the
+administrator / application developer must be aware of some of the consequences
+/ restrictions.
+
+-  The directories ``/var/run/libvirt/qemu/``, ``/var/lib/libvirt/qemu/`` and
+   ``/var/cache/libvirt/qemu/`` must all have their ownership set to match the
+   user / group ID that QEMU guests will be run as. If the vendor has set a
+   non-root user/group for the QEMU driver at build time, the permissions should
+   be set automatically at install time. If a host administrator customizes
+   user/group in ``/etc/libvirt/qemu.conf``, they will need to manually set the
+   ownership on these directories.
+
+-  When attaching USB and PCI devices to a QEMU guest, QEMU will need to access
+   files in ``/dev/bus/usb`` and ``/sys/bus/pci/devices`` respectively. The
+   libvirtd daemon will automatically set the ownership on specific devices that
+   are assigned to a guest at start time. There should not be any need for
+   administrator changes in this respect.
+
+-  Any files/devices used as guest disk images must be accessible to the
+   user/group ID that QEMU guests are configured to run as. The libvirtd daemon
+   will automatically set the ownership of the file/device path to the correct
+   user/group ID. Applications / administrators must be aware though that the
+   parent directory permissions may still deny access. The directories
+   containing disk images must either have their ownership set to match the
+   user/group configured for QEMU, or their UNIX file permissions must have the
+   'execute/search' bit enabled for 'others'.
+
+   The simplest option is the latter one, of just enabling the 'execute/search'
+   bit. For any directory to be used for storing disk images, this can be
+   achieved by running the following command on the directory itself, and any
+   parent directories
+
+   ::
+
+      chmod o+x /path/to/directory
+
+   In particular note that if using the "system" instance and attempting to
+   store disk images in a user home directory, the default permissions on $HOME
+   are typically too restrictive to allow access.
+
+The libvirt maintainers **strongly recommend against** running QEMU as the root
+user/group. This should not be required in most supported usage scenarios, as
+libvirt will generally do the right thing to grant QEMU access to files it is
+permitted to use when it is running non-root.
+
+Linux process capabilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In versions of libvirt prior to 6.0.0, even if QEMU was configured to run as the
+root user / group, libvirt would strip all process capabilities. This meant that
+QEMU could only read/write files owned by root, or with open permissions. In
+reality, stripping capabilities did not have any security benefit, as it was
+trivial to get commands to run in another context with full capabilities, for
+example, by creating a cronjob.
+
+Thus since 6.0.0, if QEMU is running as root, it will keep all process
+capabilities. Behaviour when QEMU is running non-root is unchanged, it still has
+no capabilities.
+
+SELinux basic confinement
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The basic SELinux protection for QEMU virtual machines is intended to protect
+the host OS from a compromised virtual machine process. There is no protection
+between guests.
+
+In the basic model, all QEMU virtual machines run under the confined domain
+``root:system_r:qemu_t``. It is required that any disk image assigned to a QEMU
+virtual machine is labelled with ``system_u:object_r:virt_image_t``. In a
+default deployment, package vendors/distributor will typically ensure that the
+directory ``/var/lib/libvirt/images`` has this label, such that any disk images
+created in this directory will automatically inherit the correct labelling. If
+attempting to use disk images in another location, the user/administrator must
+ensure the directory has be given this requisite label. Likewise physical block
+devices must be labelled ``system_u:object_r:virt_image_t``.
+
+Not all filesystems allow for labelling of individual files. In particular NFS,
+VFat and NTFS have no support for labelling. In these cases administrators must
+use the 'context' option when mounting the filesystem to set the default label
+to ``system_u:object_r:virt_image_t``. In the case of NFS, there is an
+alternative option, of enabling the ``virt_use_nfs`` SELinux boolean.
+
+SELinux sVirt confinement
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The SELinux sVirt protection for QEMU virtual machines builds to the basic level
+of protection, to also allow individual guests to be protected from each other.
+
+In the sVirt model, each QEMU virtual machine runs under its own confined
+domain, which is based on ``system_u:system_r:svirt_t:s0`` with a unique
+category appended, eg, ``system_u:system_r:svirt_t:s0:c34,c44``. The rules are
+setup such that a domain can only access files which are labelled with the
+matching category level, eg ``system_u:object_r:svirt_image_t:s0:c34,c44``. This
+prevents one QEMU process accessing any file resources that are prevent to
+another QEMU process.
+
+There are two ways of assigning labels to virtual machines under sVirt. In the
+default setup, if sVirt is enabled, guests will get an automatically assigned
+unique label each time they are booted. The libvirtd daemon will also
+automatically relabel exclusive access disk images to match this label. Disks
+that are marked as <shared> will get a generic label
+``system_u:system_r:svirt_image_t:s0`` allowing all guests read/write access
+them, while disks marked as <readonly> will get a generic label
+``system_u:system_r:svirt_content_t:s0`` which allows all guests read-only
+access.
+
+With statically assigned labels, the application should include the desired
+guest and file labels in the XML at time of creating the guest with libvirt. In
+this scenario the application is responsible for ensuring the disk images &
+similar resources are suitably labelled to match, libvirtd will not attempt any
+relabelling.
+
+If the sVirt security model is active, then the node capabilities XML will
+include its details. If a virtual machine is currently protected by the security
+model, then the guest XML will include its assigned labels. If enabled at
+compile time, the sVirt security model will always be activated if SELinux is
+available on the host OS. To disable sVirt, and revert to the basic level of
+SELinux protection (host protection only), the ``/etc/libvirt/qemu.conf`` file
+can be used to change the setting to ``security_driver="none"``
+
+AppArmor sVirt confinement
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When using basic AppArmor protection for the libvirtd daemon and QEMU virtual
+machines, the intention is to protect the host OS from a compromised virtual
+machine process. There is no protection between guests.
+
+The AppArmor sVirt protection for QEMU virtual machines builds on this basic
+level of protection, to also allow individual guests to be protected from each
+other.
+
+In the sVirt model, if a profile is loaded for the libvirtd daemon, then each
+``qemu:///system`` QEMU virtual machine will have a profile created for it when
+the virtual machine is started if one does not already exist. This generated
+profile uses a profile name based on the UUID of the QEMU virtual machine and
+contains rules allowing access to only the files it needs to run, such as its
+disks, pid file and log files. Just before the QEMU virtual machine is started,
+the libvirtd daemon will change into this unique profile, preventing the QEMU
+process from accessing any file resources that are present in another QEMU
+process or the host machine.
+
+The AppArmor sVirt implementation is flexible in that it allows an administrator
+to customize the template file in ``/etc/apparmor.d/libvirt/TEMPLATE`` for
+site-specific access for all newly created QEMU virtual machines. Also, when a
+new profile is generated, two files are created:
+``/etc/apparmor.d/libvirt/libvirt-<uuid>`` and
+``/etc/apparmor.d/libvirt/libvirt-<uuid>.files``. The former can be fine-tuned
+by the administrator to allow custom access for this particular QEMU virtual
+machine, and the latter will be updated appropriately when required file access
+changes, such as when a disk is added. This flexibility allows for situations
+such as having one virtual machine in complain mode with all others in enforce
+mode.
+
+While users can define their own AppArmor profile scheme, a typical
+configuration will include a profile for ``/usr/sbin/libvirtd``,
+``/usr/lib/libvirt/virt-aa-helper`` or ``/usr/libexec/virt-aa-helper``\ (a
+helper program which the libvirtd daemon uses instead of manipulating AppArmor
+directly), and an abstraction to be included by
+``/etc/apparmor.d/libvirt/TEMPLATE`` (typically
+``/etc/apparmor.d/abstractions/libvirt-qemu``). An example profile scheme can be
+found in the examples/apparmor directory of the source distribution.
+
+If the sVirt security model is active, then the node capabilities XML will
+include its details. If a virtual machine is currently protected by the security
+model, then the guest XML will include its assigned profile name. If enabled at
+compile time, the sVirt security model will be activated if AppArmor is
+available on the host OS and a profile for the libvirtd daemon is loaded when
+libvirtd is started. To disable sVirt, and revert to the basic level of AppArmor
+protection (host protection only), the ``/etc/libvirt/qemu.conf`` file can be
+used to change the setting to ``security_driver="none"``.
+
+Cgroups device ACLs
+~~~~~~~~~~~~~~~~~~~
+
+Linux kernels have a capability known as "cgroups" which is used for resource
+management. It is implemented via a number of "controllers", each controller
+covering a specific task/functional area. One of the available controllers is
+the "devices" controller, which is able to setup access control lists of
+block/character devices that a cgroup should be allowed to access. If the
+"devices" controller is mounted on a host, then libvirt will automatically
+create a dedicated cgroup for each QEMU virtual machine and setup the device
+access control list so that the QEMU process can only access shared devices, and
+explicitly assigned disks images backed by block devices.
+
+The list of shared devices a guest is allowed access to is
+
+::
+
+   /dev/null, /dev/full, /dev/zero,
+   /dev/random, /dev/urandom,
+   /dev/ptmx, /dev/kvm,
+
+In the event of unanticipated needs arising, this can be customized via the
+``/etc/libvirt/qemu.conf`` file. To mount the cgroups device controller, the
+following command should be run as root, prior to starting libvirtd
+
+::
+
+   mkdir /dev/cgroup
+   mount -t cgroup none /dev/cgroup -o devices
+
+libvirt will then place each virtual machine in a cgroup at
+``/dev/cgroup/libvirt/qemu/$VMNAME/``
+
+Import and export of libvirt domain XML configs
+-----------------------------------------------
+
+The QEMU driver currently supports a single native config format known as
+``qemu-argv``. The data for this format is expected to be a single line first a
+list of environment variables, then the QEMu binary name, finally followed by
+the QEMU command line arguments
+
+Converting from QEMU args to domain XML
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Note:** this operation is :removed:`deleted as of 5.5.0` and will return an
+error.
+
+The ``virsh domxml-from-native`` provides a way to convert an existing set of
+QEMU args into a guest description using libvirt Domain XML that can then be
+used by libvirt. Please note that this command is intended to be used to convert
+existing qemu guests previously started from the command line to be managed
+through libvirt. It should not be used a method of creating new guests from
+scratch. New guests should be created using an application calling the libvirt
+APIs (see the `libvirt applications page <apps.html>`__ for some examples) or by
+manually crafting XML to pass to virsh.
+
+Converting from domain XML to QEMU args
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-to-native`` provides a way to convert a guest description
+using libvirt Domain XML, into a set of QEMU args that can be run manually. Note
+that currently the command line formatted by libvirt is no longer suited for
+manually running qemu as the configuration expects various resources and open
+file descriptors passed to the process which are usually prepared by libvirtd.
+
+Pass-through of arbitrary qemu commands
+---------------------------------------
+
+Libvirt provides an XML namespace and an optional library ``libvirt-qemu.so``
+for dealing specifically with qemu. When used correctly, these extensions allow
+testing specific qemu features that have not yet been ported to the generic
+libvirt XML and API interfaces. However, they are **unsupported**, in that the
+library is not guaranteed to have a stable API, abusing the library or XML may
+result in inconsistent state the crashes libvirtd, and upgrading either qemu-kvm
+or libvirtd may break behavior of a domain that was relying on a qemu-specific
+pass-through. If you find yourself needing to use them to access a particular
+qemu feature, then please post an RFE to the libvirt mailing list to get that
+feature incorporated into the stable libvirt XML and API interfaces.
+
+The library provides two API: ``virDomainQemuMonitorCommand``, for sending an
+arbitrary monitor command (in either HMP or QMP format) to a qemu guest (
+:since:`Since 0.8.3` ), and ``virDomainQemuAttach``, for registering a qemu
+domain that was manually started so that it can then be managed by libvirtd (
+:since:`Since 0.9.4` , :removed:`removed as of 5.5.0` ).
+
+Additionally, the following XML additions allow fine-tuning of the command line
+given to qemu when starting a domain ( :since:`Since 0.8.3` ). In order to use
+the XML additions, it is necessary to issue an XML namespace request (the
+special ``xmlns:name`` attribute) that pulls in
+``http://libvirt.org/schemas/domain/qemu/1.0``; typically, the namespace is
+given the name of ``qemu``. With the namespace in place, it is then possible to
+add an element ``<qemu:commandline>`` under ``domain``, with the following
+sub-elements repeated as often as needed:
+
+``qemu:arg``
+   Add an additional command-line argument to the qemu process when starting the
+   domain, given by the value of the attribute ``value``.
+``qemu:env``
+   Add an additional environment variable to the qemu process when starting the
+   domain, given with the name-value pair recorded in the attributes ``name``
+   and optional ``value``.
+
+Example:
+
+::
+
+   <domain type='qemu' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
+     <name>QEMU-fedora-i686</name>
+     <memory>219200</memory>
+     <os>
+       <type arch='i686' machine='pc'>hvm</type>
+     </os>
+     <devices>
+       <emulator>/usr/bin/qemu-system-x86_64</emulator>
+     </devices>
+     <qemu:commandline>
+       <qemu:arg value='-newarg'/>
+       <qemu:env name='QEMU_ENV' value='VAL'/>
+     </qemu:commandline>
+   </domain>
+
+QEMU feature configuration for testing
+--------------------------------------
+
+In some cases e.g. when developing a new feature or for testing it may be
+required to control a given qemu feature (or qemu capability) to test it before
+it's complete or disable it for debugging purposes. :since:`Since 5.5.0` it's
+possible to use the same special qemu namespace as above
+(``http://libvirt.org/schemas/domain/qemu/1.0``) and use ``<qemu:capabilities>``
+element to add (``<qemu:add capability="capname"/>``) or remove
+(``<qemu:del capability="capname"/>``) capability bits. The naming of the
+feature bits is the same libvirt uses in the status XML. Note that this feature
+is meant for experiments only and should _not_ be used in production.
+
+Example:
+
+::
+
+   <domain type='qemu' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
+     <name>testvm</name>
+
+      [...]
+
+     <qemu:capabilities>
+       <qemu:add capability='blockdev'/>
+       <qemu:del capability='drive'/>
+     </qemu:capabilities>
+   </domain>
+
+Example domain XML config
+-------------------------
+
+QEMU emulated guest on x86_64
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+   <domain type='qemu'>
+     <name>QEMU-fedora-i686</name>
+     <uuid>c7a5fdbd-cdaf-9455-926a-d65c16db1809</uuid>
+     <memory>219200</memory>
+     <currentMemory>219200</currentMemory>
+     <vcpu>2</vcpu>
+     <os>
+       <type arch='i686' machine='pc'>hvm</type>
+       <boot dev='cdrom'/>
+     </os>
+     <devices>
+       <emulator>/usr/bin/qemu-system-x86_64</emulator>
+       <disk type='file' device='cdrom'>
+         <source file='/home/user/boot.iso'/>
+         <target dev='hdc'/>
+         <readonly/>
+       </disk>
+       <disk type='file' device='disk'>
+         <source file='/home/user/fedora.img'/>
+         <target dev='hda'/>
+       </disk>
+       <interface type='network'>
+         <source network='default'/>
+       </interface>
+       <graphics type='vnc' port='-1'/>
+     </devices>
+   </domain>
+
+KVM hardware accelerated guest on i686
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+   <domain type='kvm'>
+     <name>demo2</name>
+     <uuid>4dea24b3-1d52-d8f3-2516-782e98a23fa0</uuid>
+     <memory>131072</memory>
+     <vcpu>1</vcpu>
+     <os>
+       <type arch="i686">hvm</type>
+     </os>
+     <clock sync="localtime"/>
+     <devices>
+       <emulator>/usr/bin/qemu-kvm</emulator>
+       <disk type='file' device='disk'>
+         <source file='/var/lib/libvirt/images/demo2.img'/>
+         <target dev='hda'/>
+       </disk>
+       <interface type='network'>
+         <source network='default'/>
+         <mac address='24:42:53:21:52:45'/>
+       </interface>
+       <graphics type='vnc' port='-1' keymap='de'/>
+     </devices>
+   </domain>
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 9392c80113..a7b1a6a0bd 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -8100,4 +8100,4 @@ Example configurations for each driver are provide on the driver specific pages
 listed below

 -  `Xen examples <drvxen.html#xmlconfig>`__
--  `QEMU/KVM examples <drvqemu.html#xmlconfig>`__
+-  `QEMU/KVM examples <drvqemu.html#example-domain-xml-config>`__
diff --git a/docs/manpages/virt-qemu-run.rst b/docs/manpages/virt-qemu-run.rst
index b06c311b1d..470de93168 100644
--- a/docs/manpages/virt-qemu-run.rst
+++ b/docs/manpages/virt-qemu-run.rst
@@ -36,7 +36,7 @@ OS any opportunity to gracefully shutdown.
 **NOTE: this tool is currently considered experimental.** Its
 usage and behaviour is still subject to change in future libvirt
 releases. For further information on its usage consult the
-`QEMU driver documentation <https://libvirt.org/drvqemu.html#uriembedded>`_.
+`QEMU driver documentation <https://libvirt.org/drvqemu.html#embedded-driver>`_.

 OPTIONS
 =======
diff --git a/docs/meson.build b/docs/meson.build
index d2e685f673..2b2f7879ed 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -49,7 +49,6 @@ docs_html_in_files = [
   'drvlxc',
   'drvnodedev',
   'drvopenvz',
-  'drvqemu',
   'drvremote',
   'drvsecret',
   'drvtest',
@@ -113,6 +112,7 @@ docs_rst_files = [
   'compiling',
   'daemons',
   'developer-tooling',
+  'drvqemu',
   'formatbackup',
   'formatcheckpoint',
   'formatdomain',
-- 
2.29.2





[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux