7:10 a.m.
Peter Krempa (29):
docs: Remove empty unreferenced 'drvremote' page
docs: Convert 'cgroups' page to rST
docs: Convert 'drvbhyve' page to rST
docs: Convert 'drvesx' page to rST
docs: Convert 'drvhyperv' page to rST
docs: Convert 'drvlxc' page to rST
docs: Convert 'drvnodedev' page to rST
docs: Convert 'drvopenvz' page to rST
docs: Convert 'drvsecret' page to rST
docs: Convert 'drvtest' page to rST
docs: Convert 'drvvbox' page to rST
docs: Convert 'drvvirtuozzo' page to rST
docs: Convert 'drvvmware' page to rST
docs: Convert 'drvxen' page to rST
docs: Convert 'firewall' page to rST
docs: Convert 'format' page to rST
docs: Convert 'formatcaps' page to rST
docs: Convert 'formatdomaincaps' to rST
docs: Convert 'formatnetworkport' to rST
docs: Fix heading of 'formatnetworkport' page
docs: Convert 'formatstoragecaps' page to rST
docs: Convert 'formatstorageencryption' page to rST
docs: formatstorageencryption: Drop empty 'default' paragraph
docs: formatstorageencryption: Re-style encryption type headers
docs: Convert 'hooks' page to rST
docs: Convert 'java' page to rST
docs: Convert 'logging' page to rST
docs: logging: Replace example by link to kbase/debuglogs.html
docs: Convert 'php' page to rST
docs/cgroups.html.in | 424 --------------
docs/cgroups.rst | 364 ++++++++++++
docs/drvbhyve.html.in | 583 -------------------
docs/drvbhyve.rst | 582 +++++++++++++++++++
docs/drvesx.html.in | 838 ---------------------------
docs/drvesx.rst | 681 ++++++++++++++++++++++
docs/drvhyperv.html.in | 150 -----
docs/drvhyperv.rst | 121 ++++
docs/drvlxc.html.in | 822 --------------------------
docs/drvlxc.rst | 670 +++++++++++++++++++++
docs/drvnodedev.html.in | 383 ------------
docs/drvnodedev.rst | 348 +++++++++++
docs/drvopenvz.html.in | 123 ----
docs/drvopenvz.rst | 97 ++++
docs/drvremote.html.in | 7 -
docs/drvsecret.html.in | 82 ---
docs/drvsecret.rst | 65 +++
docs/drvtest.html.in | 27 -
docs/drvtest.rst | 21 +
docs/drvvbox.html.in | 172 ------
docs/drvvbox.rst | 161 +++++
docs/drvvirtuozzo.html.in | 70 ---
docs/drvvirtuozzo.rst | 60 ++
docs/drvvmware.html.in | 89 ---
docs/drvvmware.rst | 72 +++
docs/drvxen.html.in | 358 ------------
docs/drvxen.rst | 338 +++++++++++
docs/firewall.html.in | 523 -----------------
docs/firewall.rst | 506 ++++++++++++++++
docs/format.html.in | 48 --
docs/format.rst | 35 ++
docs/formatcaps.html.in | 219 -------
docs/formatcaps.rst | 196 +++++++
docs/formatdomain.rst | 25 +-
docs/formatdomaincaps.html.in | 693 ----------------------
docs/formatdomaincaps.rst | 602 +++++++++++++++++++
docs/formatnetworkport.html.in | 223 -------
docs/formatnetworkport.rst | 175 ++++++
docs/formatstoragecaps.html.in | 95 ---
docs/formatstoragecaps.rst | 81 +++
docs/formatstorageencryption.html.in | 181 ------
docs/formatstorageencryption.rst | 139 +++++
docs/hooks.html.in | 406 -------------
docs/hooks.rst | 518 +++++++++++++++++
docs/java.html.in | 121 ----
docs/java.rst | 128 ++++
docs/kbase/backing_chains.rst | 2 +-
docs/logging.html.in | 243 --------
docs/logging.rst | 215 +++++++
docs/meson.build | 49 +-
docs/php.html.in | 28 -
docs/php.rst | 23 +
52 files changed, 6236 insertions(+), 6946 deletions(-)
delete mode 100644 docs/cgroups.html.in
create mode 100644 docs/cgroups.rst
delete mode 100644 docs/drvbhyve.html.in
create mode 100644 docs/drvbhyve.rst
delete mode 100644 docs/drvesx.html.in
create mode 100644 docs/drvesx.rst
delete mode 100644 docs/drvhyperv.html.in
create mode 100644 docs/drvhyperv.rst
delete mode 100644 docs/drvlxc.html.in
create mode 100644 docs/drvlxc.rst
delete mode 100644 docs/drvnodedev.html.in
create mode 100644 docs/drvnodedev.rst
delete mode 100644 docs/drvopenvz.html.in
create mode 100644 docs/drvopenvz.rst
delete mode 100644 docs/drvremote.html.in
delete mode 100644 docs/drvsecret.html.in
create mode 100644 docs/drvsecret.rst
delete mode 100644 docs/drvtest.html.in
create mode 100644 docs/drvtest.rst
delete mode 100644 docs/drvvbox.html.in
create mode 100644 docs/drvvbox.rst
delete mode 100644 docs/drvvirtuozzo.html.in
create mode 100644 docs/drvvirtuozzo.rst
delete mode 100644 docs/drvvmware.html.in
create mode 100644 docs/drvvmware.rst
delete mode 100644 docs/drvxen.html.in
create mode 100644 docs/drvxen.rst
delete mode 100644 docs/firewall.html.in
create mode 100644 docs/firewall.rst
delete mode 100644 docs/format.html.in
create mode 100644 docs/format.rst
delete mode 100644 docs/formatcaps.html.in
create mode 100644 docs/formatcaps.rst
delete mode 100644 docs/formatdomaincaps.html.in
create mode 100644 docs/formatdomaincaps.rst
delete mode 100644 docs/formatnetworkport.html.in
create mode 100644 docs/formatnetworkport.rst
delete mode 100644 docs/formatstoragecaps.html.in
create mode 100644 docs/formatstoragecaps.rst
delete mode 100644 docs/formatstorageencryption.html.in
create mode 100644 docs/formatstorageencryption.rst
delete mode 100644 docs/hooks.html.in
create mode 100644 docs/hooks.rst
delete mode 100644 docs/java.html.in
create mode 100644 docs/java.rst
delete mode 100644 docs/logging.html.in
create mode 100644 docs/logging.rst
delete mode 100644 docs/php.html.in
create mode 100644 docs/php.rst
--
2.35.1
7:10 a.m.
New subject: [PATCH 01/29] docs: Remove empty unreferenced 'drvremote' page
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvremote.html.in | 7 -------
docs/meson.build | 1 -
2 files changed, 8 deletions(-)
delete mode 100644 docs/drvremote.html.in
diff --git a/docs/drvremote.html.in b/docs/drvremote.html.in
deleted file mode 100644
index 224f1bfb17..0000000000
--- a/docs/drvremote.html.in
+++ /dev/null
@@ -1,7 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Remote management driver</h1>
- </body>
-</html>
diff --git a/docs/meson.build b/docs/meson.build
index b097866208..5f26d40082 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -29,7 +29,6 @@ docs_html_in_files = [
'drvlxc',
'drvnodedev',
'drvopenvz',
- 'drvremote',
'drvsecret',
'drvtest',
'drvvbox',
--
2.35.1
7:10 a.m.
New subject: [PATCH 02/29] docs: Convert 'cgroups' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/cgroups.html.in | 424 -------------------------------------------
docs/cgroups.rst | 364 +++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 365 insertions(+), 425 deletions(-)
delete mode 100644 docs/cgroups.html.in
create mode 100644 docs/cgroups.rst
diff --git a/docs/cgroups.html.in b/docs/cgroups.html.in
deleted file mode 100644
index 412a9360ff..0000000000
--- a/docs/cgroups.html.in
+++ /dev/null
@@ -1,424 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Control Groups Resource Management</h1>
-
- <ul id="toc"></ul>
-
- <p>
- The QEMU and LXC drivers make use of the Linux "Control Groups" facility
- for applying resource management to their virtual machines and containers.
- </p>
-
- <h2><a id="requiredControllers">Required
controllers</a></h2>
-
- <p>
- The control groups filesystem supports multiple "controllers". By
default
- the init system (such as systemd) should mount all controllers compiled
- into the kernel at <code>/sys/fs/cgroup/$CONTROLLER-NAME</code>.
Libvirt
- will never attempt to mount any controllers itself, merely detect where
- they are mounted.
- </p>
-
- <p>
- The QEMU driver is capable of using the <code>cpuset</code>,
- <code>cpu</code>, <code>cpuacct</code>,
<code>memory</code>,
- <code>blkio</code> and <code>devices</code> controllers.
- None of them are compulsory. If any controller is not mounted,
- the resource management APIs which use it will cease to operate.
- It is possible to explicitly turn off use of a controller,
- even when mounted, via the <code>/etc/libvirt/qemu.conf</code>
- configuration file.
- </p>
-
- <p>
- The LXC driver is capable of using the <code>cpuset</code>,
- <code>cpu</code>, <code>cpuacct</code>,
<code>freezer</code>,
- <code>memory</code>, <code>blkio</code> and
<code>devices</code>
- controllers. The <code>cpuacct</code>,
<code>devices</code>
- and <code>memory</code> controllers are compulsory. Without
- them mounted, no containers can be started. If any of the
- other controllers are not mounted, the resource management APIs
- which use them will cease to operate.
- </p>
-
- <h2><a id="currentLayout">Current cgroups
layout</a></h2>
-
- <p>
- As of libvirt 1.0.5 or later, the cgroups layout created by libvirt has been
- simplified, in order to facilitate the setup of resource control policies by
- administrators / management applications. The new layout is based on the concepts
- of "partitions" and "consumers". A "consumer" is a
cgroup which holds the
- processes for a single virtual machine or container. A "partition" is a
cgroup
- which does not contain any processes, but can have resource controls applied.
- A "partition" will have zero or more child directories which may be
either
- "consumer" or "partition".
- </p>
-
- <p>
- As of libvirt 1.1.1 or later, the cgroups layout will have some slight
- differences when running on a host with systemd 205 or later. The overall
- tree structure is the same, but there are some differences in the naming
- conventions for the cgroup directories. Thus the following docs split
- in two, one describing systemd hosts and the other non-systemd hosts.
- </p>
-
- <h3><a id="currentLayoutSystemd">Systemd cgroups
integration</a></h3>
-
- <p>
- On hosts which use systemd, each consumer maps to a systemd scope unit,
- while partitions map to a system slice unit.
- </p>
-
- <h4><a id="systemdScope">Systemd scope
naming</a></h4>
-
- <p>
- The systemd convention is for the scope name of virtual machines / containers
- to be of the general format <code>machine-$NAME.scope</code>. Libvirt
forms the
- <code>$NAME</code> part of this by concatenating the driver type with
the id
- and truncated name of the guest, and then escaping any systemd reserved
- characters.
- So for a guest <code>demo</code> running under the
<code>lxc</code> driver,
- we get a <code>$NAME</code> of <code>lxc-12345-demo</code>
which when escaped
- is <code>lxc\x2d12345\x2ddemo</code>. So the complete scope name is
- <code>machine-lxc\x2d12345\x2ddemo.scope</code>.
- The scope names map directly to the cgroup directory names.
- </p>
-
- <h4><a id="systemdSlice">Systemd slice
naming</a></h4>
-
- <p>
- The systemd convention for slice naming is that a slice should include the
- name of all of its parents prepended on its own name. So for a libvirt
- partition <code>/machine/engineering/testing</code>, the slice name
will
- be <code>machine-engineering-testing.slice</code>. Again the slice
names
- map directly to the cgroup directory names. Systemd creates three top level
- slices by default, <code>system.slice</code>
<code>user.slice</code> and
- <code>machine.slice</code>. All virtual machines or containers created
- by libvirt will be associated with <code>machine.slice</code> by
default.
- </p>
-
- <h4><a id="systemdLayout">Systemd cgroup
layout</a></h4>
-
- <p>
- Given this, a possible systemd cgroups layout involving 3 qemu guests,
- 3 lxc containers and 3 custom child slices, would be:
- </p>
-
- <pre>
-$ROOT
- |
- +- system.slice
- | |
- | +- libvirtd.service
- |
- +- machine.slice
- |
- +- machine-qemu\x2d1\x2dvm1.scope
- | |
- | +- libvirt
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- machine-qemu\x2d2\x2dvm2.scope
- | |
- | +- libvirt
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- machine-qemu\x2d3\x2dvm3.scope
- | |
- | +- libvirt
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- machine-engineering.slice
- | |
- | +- machine-engineering-testing.slice
- | | |
- | | +- machine-lxc\x2d11111\x2dcontainer1.scope
- | |
- | +- machine-engineering-production.slice
- | |
- | +- machine-lxc\x2d22222\x2dcontainer2.scope
- |
- +- machine-marketing.slice
- |
- +- machine-lxc\x2d33333\x2dcontainer3.scope
- </pre>
-
- <p>
- Prior libvirt 7.1.0 the topology doesn't have extra
- <code>libvirt</code> directory.
- </p>
-
- <h3><a id="currentLayoutGeneric">Non-systemd cgroups
layout</a></h3>
-
- <p>
- On hosts which do not use systemd, each consumer has a corresponding cgroup
- named <code>$VMNAME.libvirt-{qemu,lxc}</code>. Each consumer is
associated
- with exactly one partition, which also have a corresponding cgroup usually
- named <code>$PARTNAME.partition</code>. The exceptions to this naming
rule
- is the top level default partition for virtual machines and containers
- <code>/machine</code>.
- </p>
-
- <p>
- Given this, a possible non-systemd cgroups layout involving 3 qemu guests,
- 3 lxc containers and 2 custom child slices, would be:
- </p>
-
- <pre>
-$ROOT
- |
- +- machine
- |
- +- qemu-1-vm1.libvirt-qemu
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- qeme-2-vm2.libvirt-qemu
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- qemu-3-vm3.libvirt-qemu
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- engineering.partition
- | |
- | +- testing.partition
- | | |
- | | +- lxc-11111-container1.libvirt-lxc
- | |
- | +- production.partition
- | |
- | +- lxc-22222-container2.libvirt-lxc
- |
- +- marketing.partition
- |
- +- lxc-33333-container3.libvirt-lxc
- </pre>
-
- <h2><a id="customPartiton">Using custom
partitions</a></h2>
-
- <p>
- If there is a need to apply resource constraints to groups of
- virtual machines or containers, then the single default
- partition <code>/machine</code> may not be sufficiently
- flexible. The administrator may wish to sub-divide the
- default partition, for example into "testing" and "production"
- partitions, and then assign each guest to a specific
- sub-partition. This is achieved via a small element addition
- to the guest domain XML config, just below the main
<code>domain</code>
- element
- </p>
-
- <pre>
-...
-<resource>
- <partition>/machine/production</partition>
-</resource>
-...
- </pre>
-
- <p>
- Note that the partition names in the guest XML are using a
- generic naming format, not the low level naming convention
- required by the underlying host OS. That is, you should not include
- any of the <code>.partition</code> or <code>.slice</code>
- suffixes in the XML config. Given a partition name
- <code>/machine/production</code>, libvirt will automatically
- apply the platform specific translation required to get
- <code>/machine/production.partition</code> (non-systemd)
- or <code>/machine.slice/machine-production.slice</code>
- (systemd) as the underlying cgroup name
- </p>
-
- <p>
- Libvirt will not auto-create the cgroups directory to back
- this partition. In the future, libvirt / virsh will provide
- APIs / commands to create custom partitions, but currently
- this is left as an exercise for the administrator.
- </p>
-
- <p>
- <strong>Note:</strong> the ability to place guests in custom
- partitions is only available with libvirt >= 1.0.5, using
- the new cgroup layout. The legacy cgroups layout described
- later in this document did not support customization per guest.
- </p>
-
- <h3><a id="createSystemd">Creating custom partitions
(systemd)</a></h3>
-
- <p>
- Given the XML config above, the admin on a systemd based host would
- need to create a unit file
<code>/etc/systemd/system/machine-production.slice</code>
- </p>
-
- <pre>
-# cat > /etc/systemd/system/machine-testing.slice <<EOF
-[Unit]
-Description=VM testing slice
-Before=slices.target
-Wants=machine.slice
-EOF
-# systemctl start machine-testing.slice
- </pre>
-
- <h3><a id="createNonSystemd">Creating custom partitions
(non-systemd)</a></h3>
-
- <p>
- Given the XML config above, the admin on a non-systemd based host
- would need to create a cgroup named '/machine/production.partition'
- </p>
-
- <pre>
-# cd /sys/fs/cgroup
-# for i in blkio cpu,cpuacct cpuset devices freezer memory net_cls perf_event
- do
- mkdir $i/machine/production.partition
- done
-# for i in cpuset.cpus cpuset.mems
- do
- cat cpuset/machine/$i > cpuset/machine/production.partition/$i
- done
-</pre>
-
- <h2><a id="resourceAPIs">Resource management
APIs/commands</a></h2>
-
- <p>
- Since libvirt aims to provide an API which is portable across
- hypervisors, the concept of cgroups is not exposed directly
- in the API or XML configuration. It is considered to be an
- internal implementation detail. Instead libvirt provides a
- set of APIs for applying resource controls, which are then
- mapped to corresponding cgroup tunables
- </p>
-
- <h3>Scheduler tuning</h3>
-
- <p>
- Parameters from the "cpu" controller are exposed via the
- <code>schedinfo</code> command in virsh.
- </p>
-
- <pre>
-# virsh schedinfo demo
-Scheduler : posix
-cpu_shares : 1024
-vcpu_period : 100000
-vcpu_quota : -1
-emulator_period: 100000
-emulator_quota : -1</pre>
-
-
- <h3>Block I/O tuning</h3>
-
- <p>
- Parameters from the "blkio" controller are exposed via the
- <code>bkliotune</code> command in virsh.
- </p>
-
-
- <pre>
-# virsh blkiotune demo
-weight : 500
-device_weight : </pre>
-
- <h3>Memory tuning</h3>
-
- <p>
- Parameters from the "memory" controller are exposed via the
- <code>memtune</code> command in virsh.
- </p>
-
- <pre>
-# virsh memtune demo
-hard_limit : 580192
-soft_limit : unlimited
-swap_hard_limit: unlimited
- </pre>
-
- <h3>Network tuning</h3>
-
- <p>
- The <code>net_cls</code> is not currently used. Instead traffic
- filter policies are set directly against individual virtual
- network interfaces.
- </p>
-
- <h2><a id="legacyLayout">Legacy cgroups
layout</a></h2>
-
- <p>
- Prior to libvirt 1.0.5, the cgroups layout created by libvirt was different
- from that described above, and did not allow for administrator customization.
- Libvirt used a fixed, 3-level hierarchy
<code>libvirt/{qemu,lxc}/$VMNAME</code>
- which was rooted at the point in the hierarchy where libvirtd itself was
- located. So if libvirtd was placed at
<code>/system/libvirtd.service</code>
- by systemd, the groups for each virtual machine / container would be located
- at <code>/system/libvirtd.service/libvirt/{qemu,lxc}/$VMNAME</code>. In
addition
- to this, the QEMU drivers further child groups for each vCPU thread and the
- emulator thread(s). This leads to a hierarchy that looked like
- </p>
-
-
- <pre>
-$ROOT
- |
- +- system
- |
- +- libvirtd.service
- |
- +- libvirt
- |
- +- qemu
- | |
- | +- vm1
- | | |
- | | +- emulator
- | | +- vcpu0
- | | +- vcpu1
- | |
- | +- vm2
- | | |
- | | +- emulator
- | | +- vcpu0
- | | +- vcpu1
- | |
- | +- vm3
- | |
- | +- emulator
- | +- vcpu0
- | +- vcpu1
- |
- +- lxc
- |
- +- container1
- |
- +- container2
- |
- +- container3
- </pre>
-
- <p>
- Although current releases are much improved, historically the use of deep
- hierarchies has had a significant negative impact on the kernel scalability.
- The legacy libvirt cgroups layout highlighted these problems, to the detriment
- of the performance of virtual machines and containers.
- </p>
- </body>
-</html>
diff --git a/docs/cgroups.rst b/docs/cgroups.rst
new file mode 100644
index 0000000000..eb66a14f0d
--- /dev/null
+++ b/docs/cgroups.rst
@@ -0,0 +1,364 @@
+==================================
+Control Groups Resource Management
+==================================
+
+.. contents::
+
+The QEMU and LXC drivers make use of the Linux "Control Groups" facility for
+applying resource management to their virtual machines and containers.
+
+Required controllers
+--------------------
+
+The control groups filesystem supports multiple "controllers". By default the
+init system (such as systemd) should mount all controllers compiled into the
+kernel at ``/sys/fs/cgroup/$CONTROLLER-NAME``. Libvirt will never attempt to
+mount any controllers itself, merely detect where they are mounted.
+
+The QEMU driver is capable of using the ``cpuset``, ``cpu``, ``cpuacct``,
+``memory``, ``blkio`` and ``devices`` controllers. None of them are compulsory.
+If any controller is not mounted, the resource management APIs which use it will
+cease to operate. It is possible to explicitly turn off use of a controller,
+even when mounted, via the ``/etc/libvirt/qemu.conf`` configuration file.
+
+The LXC driver is capable of using the ``cpuset``, ``cpu``, ``cpuacct``,
+``freezer``, ``memory``, ``blkio`` and ``devices`` controllers. The ``cpuacct``,
+``devices`` and ``memory`` controllers are compulsory. Without them mounted, no
+containers can be started. If any of the other controllers are not mounted, the
+resource management APIs which use them will cease to operate.
+
+Current cgroups layout
+----------------------
+
+As of libvirt 1.0.5 or later, the cgroups layout created by libvirt has been
+simplified, in order to facilitate the setup of resource control policies by
+administrators / management applications. The new layout is based on the
+concepts of "partitions" and "consumers". A "consumer" is a
cgroup which holds
+the processes for a single virtual machine or container. A "partition" is a
+cgroup which does not contain any processes, but can have resource controls
+applied. A "partition" will have zero or more child directories which may be
+either "consumer" or "partition".
+
+As of libvirt 1.1.1 or later, the cgroups layout will have some slight
+differences when running on a host with systemd 205 or later. The overall tree
+structure is the same, but there are some differences in the naming conventions
+for the cgroup directories. Thus the following docs split in two, one describing
+systemd hosts and the other non-systemd hosts.
+
+Systemd cgroups integration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On hosts which use systemd, each consumer maps to a systemd scope unit, while
+partitions map to a system slice unit.
+
+Systemd scope naming
+^^^^^^^^^^^^^^^^^^^^
+
+The systemd convention is for the scope name of virtual machines / containers to
+be of the general format ``machine-$NAME.scope``. Libvirt forms the ``$NAME``
+part of this by concatenating the driver type with the id and truncated name of
+the guest, and then escaping any systemd reserved characters. So for a guest
+``demo`` running under the ``lxc`` driver, we get a ``$NAME`` of
+``lxc-12345-demo`` which when escaped is ``lxc\x2d12345\x2ddemo``. So the
+complete scope name is ``machine-lxc\x2d12345\x2ddemo.scope``. The scope names
+map directly to the cgroup directory names.
+
+Systemd slice naming
+^^^^^^^^^^^^^^^^^^^^
+
+The systemd convention for slice naming is that a slice should include the name
+of all of its parents prepended on its own name. So for a libvirt partition
+``/machine/engineering/testing``, the slice name will be
+``machine-engineering-testing.slice``. Again the slice names map directly to the
+cgroup directory names. Systemd creates three top level slices by default,
+``system.slice`` ``user.slice`` and ``machine.slice``. All virtual machines or
+containers created by libvirt will be associated with ``machine.slice`` by
+default.
+
+Systemd cgroup layout
+^^^^^^^^^^^^^^^^^^^^^
+
+Given this, a possible systemd cgroups layout involving 3 qemu guests, 3 lxc
+containers and 3 custom child slices, would be:
+
+::
+
+ $ROOT
+ |
+ +- system.slice
+ | |
+ | +- libvirtd.service
+ |
+ +- machine.slice
+ |
+ +- machine-qemu\x2d1\x2dvm1.scope
+ | |
+ | +- libvirt
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- machine-qemu\x2d2\x2dvm2.scope
+ | |
+ | +- libvirt
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- machine-qemu\x2d3\x2dvm3.scope
+ | |
+ | +- libvirt
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- machine-engineering.slice
+ | |
+ | +- machine-engineering-testing.slice
+ | | |
+ | | +- machine-lxc\x2d11111\x2dcontainer1.scope
+ | |
+ | +- machine-engineering-production.slice
+ | |
+ | +- machine-lxc\x2d22222\x2dcontainer2.scope
+ |
+ +- machine-marketing.slice
+ |
+ +- machine-lxc\x2d33333\x2dcontainer3.scope
+
+Prior libvirt 7.1.0 the topology doesn't have extra ``libvirt`` directory.
+
+Non-systemd cgroups layout
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On hosts which do not use systemd, each consumer has a corresponding cgroup
+named ``$VMNAME.libvirt-{qemu,lxc}``. Each consumer is associated with exactly
+one partition, which also have a corresponding cgroup usually named
+``$PARTNAME.partition``. The exceptions to this naming rule is the top level
+default partition for virtual machines and containers ``/machine``.
+
+Given this, a possible non-systemd cgroups layout involving 3 qemu guests, 3 lxc
+containers and 2 custom child slices, would be:
+
+::
+
+ $ROOT
+ |
+ +- machine
+ |
+ +- qemu-1-vm1.libvirt-qemu
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- qeme-2-vm2.libvirt-qemu
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- qemu-3-vm3.libvirt-qemu
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- engineering.partition
+ | |
+ | +- testing.partition
+ | | |
+ | | +- lxc-11111-container1.libvirt-lxc
+ | |
+ | +- production.partition
+ | |
+ | +- lxc-22222-container2.libvirt-lxc
+ |
+ +- marketing.partition
+ |
+ +- lxc-33333-container3.libvirt-lxc
+
+Using custom partitions
+-----------------------
+
+If there is a need to apply resource constraints to groups of virtual machines
+or containers, then the single default partition ``/machine`` may not be
+sufficiently flexible. The administrator may wish to sub-divide the default
+partition, for example into "testing" and "production" partitions,
and then
+assign each guest to a specific sub-partition. This is achieved via a small
+element addition to the guest domain XML config, just below the main ``domain``
+element
+
+::
+
+ ...
+ <resource>
+ <partition>/machine/production</partition>
+ </resource>
+ ...
+
+Note that the partition names in the guest XML are using a generic naming
+format, not the low level naming convention required by the underlying host OS.
+That is, you should not include any of the ``.partition`` or ``.slice`` suffixes
+in the XML config. Given a partition name ``/machine/production``, libvirt will
+automatically apply the platform specific translation required to get
+``/machine/production.partition`` (non-systemd) or
+``/machine.slice/machine-production.slice`` (systemd) as the underlying cgroup
+name
+
+Libvirt will not auto-create the cgroups directory to back this partition. In
+the future, libvirt / virsh will provide APIs / commands to create custom
+partitions, but currently this is left as an exercise for the administrator.
+
+**Note:** the ability to place guests in custom partitions is only available
+with libvirt >= 1.0.5, using the new cgroup layout. The legacy cgroups layout
+described later in this document did not support customization per guest.
+
+Creating custom partitions (systemd)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Given the XML config above, the admin on a systemd based host would need to
+create a unit file ``/etc/systemd/system/machine-production.slice``
+
+::
+
+ # cat > /etc/systemd/system/machine-testing.slice <<EOF
+ [Unit]
+ Description=VM testing slice
+ Before=slices.target
+ Wants=machine.slice
+ EOF
+ # systemctl start machine-testing.slice
+
+Creating custom partitions (non-systemd)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Given the XML config above, the admin on a non-systemd based host would need to
+create a cgroup named '/machine/production.partition'
+
+::
+
+ # cd /sys/fs/cgroup
+ # for i in blkio cpu,cpuacct cpuset devices freezer memory net_cls perf_event
+ do
+ mkdir $i/machine/production.partition
+ done
+ # for i in cpuset.cpus cpuset.mems
+ do
+ cat cpuset/machine/$i > cpuset/machine/production.partition/$i
+ done
+
+Resource management APIs/commands
+---------------------------------
+
+Since libvirt aims to provide an API which is portable across hypervisors, the
+concept of cgroups is not exposed directly in the API or XML configuration. It
+is considered to be an internal implementation detail. Instead libvirt provides
+a set of APIs for applying resource controls, which are then mapped to
+corresponding cgroup tunables
+
+Scheduler tuning
+~~~~~~~~~~~~~~~~
+
+Parameters from the "cpu" controller are exposed via the ``schedinfo`` command
+in virsh.
+
+::
+
+ # virsh schedinfo demo
+ Scheduler : posix
+ cpu_shares : 1024
+ vcpu_period : 100000
+ vcpu_quota : -1
+ emulator_period: 100000
+ emulator_quota : -1
+
+Block I/O tuning
+~~~~~~~~~~~~~~~~
+
+Parameters from the "blkio" controller are exposed via the ``bkliotune``
command
+in virsh.
+
+::
+
+ # virsh blkiotune demo
+ weight : 500
+ device_weight :
+
+Memory tuning
+~~~~~~~~~~~~~
+
+Parameters from the "memory" controller are exposed via the ``memtune``
command
+in virsh.
+
+::
+
+ # virsh memtune demo
+ hard_limit : 580192
+ soft_limit : unlimited
+ swap_hard_limit: unlimited
+
+Network tuning
+~~~~~~~~~~~~~~
+
+The ``net_cls`` is not currently used. Instead traffic filter policies are set
+directly against individual virtual network interfaces.
+
+Legacy cgroups layout
+---------------------
+
+Prior to libvirt 1.0.5, the cgroups layout created by libvirt was different from
+that described above, and did not allow for administrator customization. Libvirt
+used a fixed, 3-level hierarchy ``libvirt/{qemu,lxc}/$VMNAME`` which was rooted
+at the point in the hierarchy where libvirtd itself was located. So if libvirtd
+was placed at ``/system/libvirtd.service`` by systemd, the groups for each
+virtual machine / container would be located at
+``/system/libvirtd.service/libvirt/{qemu,lxc}/$VMNAME``. In addition to this,
+the QEMU drivers further child groups for each vCPU thread and the emulator
+thread(s). This leads to a hierarchy that looked like
+
+::
+
+ $ROOT
+ |
+ +- system
+ |
+ +- libvirtd.service
+ |
+ +- libvirt
+ |
+ +- qemu
+ | |
+ | +- vm1
+ | | |
+ | | +- emulator
+ | | +- vcpu0
+ | | +- vcpu1
+ | |
+ | +- vm2
+ | | |
+ | | +- emulator
+ | | +- vcpu0
+ | | +- vcpu1
+ | |
+ | +- vm3
+ | |
+ | +- emulator
+ | +- vcpu0
+ | +- vcpu1
+ |
+ +- lxc
+ |
+ +- container1
+ |
+ +- container2
+ |
+ +- container3
+
+Although current releases are much improved, historically the use of deep
+hierarchies has had a significant negative impact on the kernel scalability. The
+legacy libvirt cgroups layout highlighted these problems, to the detriment of
+the performance of virtual machines and containers.
diff --git a/docs/meson.build b/docs/meson.build
index 5f26d40082..bb7e27e031 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -19,7 +19,6 @@ docs_assets = [
docs_html_in_files = [
'404',
- 'cgroups',
'csharp',
'dbus',
'docs',
@@ -70,6 +69,7 @@ docs_rst_files = [
'best-practices',
'bindings',
'bugs',
+ 'cgroups',
'ci',
'coding-style',
'committer-guidelines',
--
2.35.1
7:10 a.m.
New subject: [PATCH 03/29] docs: Convert 'drvbhyve' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvbhyve.html.in | 583 ------------------------------------------
docs/drvbhyve.rst | 582 +++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 583 insertions(+), 584 deletions(-)
delete mode 100644 docs/drvbhyve.html.in
create mode 100644 docs/drvbhyve.rst
diff --git a/docs/drvbhyve.html.in b/docs/drvbhyve.html.in
deleted file mode 100644
index 228e8b2bd5..0000000000
--- a/docs/drvbhyve.html.in
+++ /dev/null
@@ -1,583 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Bhyve driver</h1>
-
- <ul id="toc"></ul>
-
-<p>
-Bhyve is a FreeBSD hypervisor. It first appeared in FreeBSD 10.0. However, it's
-recommended to keep tracking FreeBSD 10-STABLE to make sure all new features
-of bhyve are supported.
-
-In order to enable bhyve on your FreeBSD host, you'll need to load the
<code>vmm</code>
-kernel module. Additionally, <code>if_tap</code> and
<code>if_bridge</code> modules
-should be loaded for networking support. Also, <span class="since">since
3.2.0</span> the
-<code>virt-host-validate(1)</code> supports the bhyve host validation and
could be
-used like this:
-</p>
-
-<pre>
-$ virt-host-validate bhyve
- BHYVE: Checking for vmm module : PASS
- BHYVE: Checking for if_tap module : PASS
- BHYVE: Checking for if_bridge module : PASS
- BHYVE: Checking for nmdm module : PASS
-$
-</pre>
-
-<p>
-Additional information on bhyve could be obtained on <a
href="https://bhyve.org/">bhyve.org</a>;.
-</p>
-
-<h2><a id="uri">Connections to the Bhyve
driver</a></h2>
-<p>
-The libvirt bhyve driver is a single-instance privileged driver. Some sample
-connection URIs are:
-</p>
-
-<pre>
-bhyve:///system (local access)
-bhyve+unix:///system (local access)
-bhyve+ssh://root@example.com/system (remote access, SSH tunnelled)
-</pre>
-
-<h2><a id="exconfig">Example guest domain XML
configurations</a></h2>
-
-<h3>Example config</h3>
-<p>
-The bhyve driver in libvirt is in its early stage and under active development. So it
supports
-only limited number of features bhyve provides.
-</p>
-
-<p>
-Note: in older libvirt versions, only a single network device and a single
-disk device were supported per-domain. However,
-<span class="since">since 1.2.6</span> the libvirt bhyve driver
supports
-up to 31 PCI devices.
-</p>
-
-<p>
-Note: the Bhyve driver in libvirt will boot whichever device is first. If you
-want to install from CD, put the CD device first. If not, put the root HDD
-first.
-</p>
-
-<p>
-Note: Only the SATA bus is supported. Only <code>cdrom</code>- and
-<code>disk</code>-type disks are supported.
-</p>
-
-<pre>
-<domain type='bhyve'>
- <name>bhyve</name>
- <uuid>df3be7e7-a104-11e3-aeb0-50e5492bd3dc</uuid>
- <memory>219136</memory>
- <currentMemory>219136</currentMemory>
- <vcpu>1</vcpu>
- <os>
- <type>hvm</type>
- </os>
- <features>
- <apic/>
- <acpi/>
- </features>
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>destroy</on_crash>
- <devices>
- <disk type='file'>
- <driver name='file' type='raw'/>
- <source file='/path/to/bhyve_freebsd.img'/>
- <target dev='hda' bus='sata'/>
- </disk>
- <disk type='file' device='cdrom'>
- <driver name='file' type='raw'/>
- <source file='/path/to/cdrom.iso'/>
- <target dev='hdc' bus='sata'/>
- <readonly/>
- </disk>
- <interface type='bridge'>
- <model type='virtio'/>
- <source bridge="virbr0"/>
- </interface>
- </devices>
-</domain>
-</pre>
-
-<p>(The <disk> sections may be swapped in order to install from
-<em>cdrom.iso</em>.)</p>
-
-<h3>Example config (Linux guest)</h3>
-
-<p>
-Note the addition of <bootloader>.
-</p>
-
-<pre>
-<domain type='bhyve'>
- <name>linux_guest</name>
- <uuid>df3be7e7-a104-11e3-aeb0-50e5492bd3dc</uuid>
- <memory>131072</memory>
- <currentMemory>131072</currentMemory>
- <vcpu>1</vcpu>
- <bootloader>/usr/local/sbin/grub-bhyve</bootloader>
- <os>
- <type>hvm</type>
- </os>
- <features>
- <apic/>
- <acpi/>
- </features>
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>destroy</on_crash>
- <devices>
- <disk type='file' device='disk'>
- <driver name='file' type='raw'/>
- <source file='/path/to/guest_hdd.img'/>
- <target dev='hda' bus='sata'/>
- </disk>
- <disk type='file' device='cdrom'>
- <driver name='file' type='raw'/>
- <source file='/path/to/cdrom.iso'/>
- <target dev='hdc' bus='sata'/>
- <readonly/>
- </disk>
- <interface type='bridge'>
- <model type='virtio'/>
- <source bridge="virbr0"/>
- </interface>
- </devices>
-</domain>
-</pre>
-
-<h3>Example config (Linux UEFI guest, VNC, tablet)</h3>
-
-<p>This is an example to boot into Fedora 25 installation:</p>
-
-<pre>
-<domain type='bhyve'>
- <name>fedora_uefi_vnc_tablet</name>
- <memory unit='G'>4</memory>
- <vcpu>2</vcpu>
- <os>
- <type>hvm</type>
- <b><loader readonly="yes"
type="pflash">/usr/local/share/uefi-firmware/BHYVE_UEFI.fd</loader></b>
- </os>
- <features>
- <apic/>
- <acpi/>
- </features>
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>destroy</on_crash>
- <devices>
- <disk type='file' device='cdrom'>
- <driver name='file' type='raw'/>
- <source
file='/path/to/Fedora-Workstation-Live-x86_64-25-1.3.iso'/>
- <target dev='hdc' bus='sata'/>
- <readonly/>
- </disk>
- <disk type='file' device='disk'>
- <driver name='file' type='raw'/>
- <source file='/path/to/linux_uefi.img'/>
- <target dev='hda' bus='sata'/>
- </disk>
- <interface type='bridge'>
- <model type='virtio'/>
- <source bridge="virbr0"/>
- </interface>
- <serial type="nmdm">
- <source master="/dev/nmdm0A"
slave="/dev/nmdm0B"/>
- </serial>
- <b><graphics type='vnc' port='5904'>
- <listen type='address' address='127.0.0.1'/>
- </graphics>
- <controller type='usb' model='nec-xhci'/>
- <input type='tablet' bus='usb'/></b>
- </devices>
-</domain>
-</pre>
-
-<p>Please refer to the <a href="#uefi">UEFI</a> section for a
more detailed explanation.</p>
-
-<h2><a id="usage">Guest usage / management</a></h2>
-
-<h3><a id="console">Connecting to a guest
console</a></h3>
-
-<p>
-Guest console connection is supported through the <code>nmdm</code> device.
It could be enabled by adding
-the following to the domain XML (<span class="since">Since
1.2.4</span>):
-</p>
-
-<pre>
-...
-<devices>
- <serial type="nmdm">
- <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/>
- </serial>
-</devices>
-...</pre>
-
-
-<p>Make sure to load the <code>nmdm</code> kernel module if you plan to
use that.</p>
-
-<p>
-Then <code>virsh console</code> command can be used to connect to the text
console
-of a guest.</p>
-
-<p><b>NB:</b> Some versions of bhyve have a bug that prevents guests
from booting
-until the console is opened by a client. This bug was fixed in
-<a href="https://svnweb.freebsd.org/changeset/base/262884">FreeBSD
changeset r262884</a>. If
-an older version is used, one either has to open a console manually with
<code>virsh console</code>
-to let a guest boot or start a guest using:</p>
-
-<pre>start --console domname</pre>
-
-<p><b>NB:</b> A bootloader configured to require user interaction will
prevent
-the domain from starting (and thus <code>virsh console</code> or
<code>start
---console</code> from functioning) until the user interacts with it manually on
-the VM host. Because users typically do not have access to the VM host,
-interactive bootloaders are unsupported by libvirt. <em>However,</em> if you
happen to
-run into this scenario and also happen to have access to the Bhyve host
-machine, you may select a boot option and allow the domain to finish starting
-by using an alternative terminal client on the VM host to connect to the
-domain-configured null modem device. One example (assuming
-<code>/dev/nmdm0B</code> is configured as the slave end of the domain serial
-device) is:</p>
-
-<pre>cu -l /dev/nmdm0B</pre>
-
-<h3><a id="xmltonative">Converting from domain XML to Bhyve
args</a></h3>
-
-<p>
-The <code>virsh domxml-to-native</code> command can preview the actual
-<code>bhyve</code> commands that will be executed for a given domain.
-It outputs two lines, the first line is a <code>bhyveload</code> command and
-the second is a <code>bhyve</code> command.
-</p>
-
-<p>Please note that the <code>virsh domxml-to-native</code> doesn't
do any
-real actions other than printing the command, for example, it doesn't try to
-find a proper TAP interface and create it, like what is done when starting
-a domain; and always returns <code>tap0</code> for the network interface. So
-if you're going to run these commands manually, most likely you might want to
-tweak them.</p>
-
-<pre>
-# virsh -c "bhyve:///system" domxml-to-native --format bhyve-argv --xml
/path/to/bhyve.xml
-/usr/sbin/bhyveload -m 214 -d /home/user/vm1.img vm1
-/usr/sbin/bhyve -c 2 -m 214 -A -I -H -P -s 0:0,hostbridge \
- -s 3:0,virtio-net,tap0,mac=52:54:00:5d:74:e3 -s 2:0,virtio-blk,/home/user/vm1.img \
- -s 1,lpc -l com1,/dev/nmdm0A vm1
-</pre>
-
-<h3><a id="zfsvolume">Using ZFS volumes</a></h3>
-
-<p>It's possible to use ZFS volumes as disk devices <span
class="since">since 1.2.8</span>.
-An example of domain XML device entry for that will look like:</p>
-
-<pre>
-...
-<disk type='volume' device='disk'>
- <source pool='zfspool' volume='vol1'/>
- <target dev='vdb' bus='virtio'/>
-</disk>
-...</pre>
-
-<p>Please refer to the <a href="storage.html">Storage
documentation</a> for more details on storage
-management.</p>
-
-<h3><a id="grubbhyve">Using grub2-bhyve or Alternative
Bootloaders</a></h3>
-
-<p>It's possible to boot non-FreeBSD guests by specifying an explicit
-bootloader, e.g. <code>grub-bhyve(1)</code>. Arguments to the bootloader may
be
-specified as well. If the bootloader is <code>grub-bhyve</code> and
arguments
-are omitted, libvirt will try and infer boot ordering from user-supplied
-<boot order='N'> configuration in the domain. Failing that, it will
boot
-the first disk in the domain (either <code>cdrom</code>- or
-<code>disk</code>-type devices). If the disk type is
<code>disk</code>, it will
-attempt to boot from the first partition in the disk image.</p>
-
-<pre>
-...
-<bootloader>/usr/local/sbin/grub-bhyve</bootloader>
-<bootloader_args>...</bootloader_args>
-...
-</pre>
-
-<p>Caveat: <code>bootloader_args</code> does not support any quoting.
-Filenames, etc, must not have spaces or they will be tokenized incorrectly.</p>
-
-<h3><a id="uefi">Using UEFI bootrom, VNC, and USB
tablet</a></h3>
-
-<p><span class="since">Since 3.2.0</span>, in addition to
<a href="#grubbhyve">grub-bhyve</a>,
-non-FreeBSD guests could be also booted using an UEFI boot ROM, provided both guest OS
and
-installed <code>bhyve(1)</code> version support UEFI. To use that,
<code>loader</code>
-should be specified in the <code>os</code> section:</p>
-
-<pre>
-<domain type='bhyve'>
- ...
- <os>
- <type>hvm</type>
- <loader readonly="yes"
type="pflash">/usr/local/share/uefi-firmware/BHYVE_UEFI.fd</loader>
- </os>
- ...
-</pre>
-
-<p>This uses the UEFI firmware provided by
-the <a
href="https://www.freshports.org/sysutils/bhyve-firmware/">s...
-FreeBSD port.</p>
-
-<p>VNC and the tablet input device could be configured this way:</p>
-
-<pre>
-<domain type='bhyve'>
- <devices>
- ...
- <graphics type='vnc' port='5904'>
- <listen type='address' address='127.0.0.1'/>
- </graphics>
- <controller type='usb' model='nec-xhci'/>
- <input type='tablet' bus='usb'/>
- </devices>
- ...
-</domain>
-</pre>
-
-<p>This way, VNC will be accessible on
<code>127.0.0.1:5904</code>.</p>
-
-<p>Please note that the tablet device requires to have a USB controller
-of the <code>nec-xhci</code> model. Currently, only a single controller of
this
-type and a single tablet are supported per domain.</p>
-
-<p><span class="since">Since 3.5.0</span>, it's possible
to configure how the video device is exposed
-to the guest using the <code>vgaconf</code> attribute:</p>
-
-<pre>
-<domain type='bhyve'>
- <devices>
- ...
- <graphics type='vnc' port='5904'>
- <listen type='address' address='127.0.0.1'/>
- </graphics>
- <video>
- <driver vgaconf='on'/>
- <model type='gop' heads='1'
primary='yes'/>
- </video>
- ...
- </devices>
- ...
-</domain>
-</pre>
-
-<p>If not specified, bhyve's default mode for <code>vgaconf</code>
-will be used. Please refer to the
-<a
href="https://www.freebsd.org/cgi/man.cgi?query=bhyve&sektio...
-manual page and the <a href="https://wiki.freebsd.org/bhyve">bhyve
wiki</a> for more details on using
-the <code>vgaconf</code> option.</p>
-
-<p><span class="since">Since 3.7.0</span>, it's possible
to use <code>autoport</code>
-to let libvirt allocate VNC port automatically (instead of explicitly specifying
-it with the <code>port</code> attribute):</p>
-
-<pre>
- <graphics type='vnc' autoport='yes'>
-</pre>
-
-<p><span class="since">Since 6.8.0</span>, it's possible
to set framebuffer resolution
-using the <code>resolution</code> sub-element:</p>
-
-<pre>
- <video>
- <model type='gop' heads='1' primary='yes'>
- <resolution x='800' y='600'/>
- </model>
- </video>
-</pre>
-
-<p><span class="since">Since 6.8.0</span>, VNC server can be
configured to use
-password based authentication:</p>
-
-<pre>
- <graphics type='vnc' port='5904'
passwd='foobar'>
- <listen type='address' address='127.0.0.1'/>
- </graphics>
-</pre>
-
-<p>Note: VNC password authentication is known to be cryptographically weak.
-Additionally, the password is passed as a command line argument in clear text.
-Make sure you understand the risks associated with this feature before using
it.</p>
-
-<h3><a id="clockconfig">Clock configuration</a></h3>
-
-<p>Originally bhyve supported only localtime for RTC. Support for UTC time was
introduced in
-<a href="https://svnweb.freebsd.org/changeset/base/284894">FreeBSD
changeset r284894</a>
-for <i>10-STABLE</i> and
-in <a href="https://svnweb.freebsd.org/changeset/base/279225">chan...
r279225</a>
-for <i>-CURRENT</i>. It's possible to use this in libvirt <span
class="since">since 1.2.18</span>,
-just place the following to domain XML:</p>
-
-<pre>
-<domain type="bhyve">
- ...
- <clock offset='utc'/>
- ...
-</domain>
-</pre>
-
-<p>Please note that if you run the older bhyve version that doesn't support UTC
time, you'll
-fail to start a domain. As UTC is used as a default when you do not specify clock
settings,
-you'll need to explicitly specify 'localtime' in this case:</p>
-
-<pre>
-<domain type="bhyve">
- ...
- <clock offset='localtime'/>
- ...
-</domain>
-</pre>
-
-<h3><a id="e1000">e1000 NIC</a></h3>
-
-<p>As of <a
href="https://svnweb.freebsd.org/changeset/base/302504">FreeBSD changeset
r302504</a>
-bhyve supports Intel e1000 network adapter emulation. It's supported in libvirt
-<span class="since">since 3.1.0</span> and could be used as
follows:</p>
-
-<pre>
-...
- <interface type='bridge'>
- <source bridge='virbr0'/>
- <model type='<b>e1000</b>'/>
- </interface>
-...
-</pre>
-
-<h3><a id="sound">Sound device</a></h3>
-
-<p>As of <a
href="https://svnweb.freebsd.org/changeset/base/349355">FreeBSD changeset
r349355</a>
-bhyve supports sound device emulation. It's supported in libvirt
-<span class="since">since 6.7.0</span>.</p>
-
-<pre>
-...
- <sound model='ich7'>
- <audio id='1'/>
- </sound>
- <audio id='1' type='oss'>
- <input dev='/dev/dsp0'/>
- <output dev='/dev/dsp0'/>
- </audio>
-...
-</pre>
-
-<p>Here, the <code>sound</code> element specifies the sound device as
it's exposed
-to the guest, with <code>ich7</code> being the only supported model now,
-and the <code>audio</code> element specifies how the guest device is mapped
-to the host sound device.</p>
-
-<h3><a id="fs-9p">Virtio-9p filesystem</a></h3>
-
-<p>As of <a
href="https://svnweb.freebsd.org/changeset/base/366413">FreeBSD changeset
r366413</a>
-bhyve supports sharing arbitrary directory tree between the guest and the host.
-It's supported in libvirt <span class="since">since
6.9.0</span>.</p>
-
-<pre>
-...
- <filesystem>
- <source dir='/shared/dir'/>
- <target dir='shared_dir'/>
- </filesystem>
-...
-</pre>
-
-<p>This share could be made read only by adding the
<code><readonly/></code> sub-element.</p>
-
-<p>In the Linux guest, this could be mounted using:</p>
-
-<pre>mount -t 9p shared_dir /mnt/shared_dir</pre>
-
-<h3><a id="wired">Wiring guest memory</a></h3>
-
-<p><span class="since">Since 4.4.0</span>, it's possible
to specify that guest memory should
-be wired and cannot be swapped out as follows:</p>
-<pre>
-<domain type="bhyve">
- ...
- <memoryBacking>
- <locked/>
- </memoryBacking>
- ...
-</domain>
-</pre>
-
-<h3><a id="cputopology">CPU topology</a></h3>
-
-<p><span class="since">Since 4.5.0</span>, it's possible
to specify guest CPU topology, if bhyve
-supports that. Support for specifying guest CPU topology was added to bhyve in
-<a href="https://svnweb.freebsd.org/changeset/base/332298">FreeBSD
changeset r332298</a>
-for <i>-CURRENT</i>.
-Example:</p>
-<pre>
-<domain type="bhyve">
- ...
- <cpu>
- <topology sockets='1' cores='2'
threads='1'/>
- </cpu>
- ...
-</domain>
-</pre>
-
-<h3><a id="msrs">Ignoring unknown MSRs reads and
writes</a></h3>
-
-<p><span class="since">Since 5.1.0</span>, it's possible
to make bhyve
-ignore accesses to unimplemented Model Specific Registers (MSRs).
-Example:</p>
-
-<pre>
-<domain type="bhyve">
- ...
- <features>
- ...
- <msrs unknown='ignore'/>
- ...
- </features>
- ...
-</domain>
-</pre>
-
-<h3><a id="bhyvecommand">Pass-through of arbitrary bhyve
commands</a></h3>
-
-<p><span class="since">Since 5.1.0</span>, it's possible
to pass additional command-line
-arguments to the bhyve process when starting the domain using the
-<code><bhyve:commandline></code> element under
<code>domain</code>.
-To supply an argument, use the element <code><bhyve:arg></code>
with
-the attribute <code>value</code> set to additional argument to be added.
-The arg element may be repeated multiple times. To use this XML addition, 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/bhyve/1.0</code>;
-typically, the namespace is given the name of <code>bhyve</code>.
-</p>
-<p>Example:</p>
-<pre>
-<domain type="bhyve"
xmlns:bhyve="http://libvirt.org/schemas/domain/bhyve/1.0">
- ...
- <bhyve:commandline>
- <bhyve:arg value='-somebhyvearg'/>
- </bhyve:commandline>
-</domain>
-</pre>
-
-<p>Note that these extensions are for testing and development purposes only.
-They are <b>unsupported</b>, using them may result in inconsistent state,
-and upgrading either bhyve or libvirtd maybe break behavior of a domain that
-was relying on a specific commands pass-through.</p>
-
- </body>
-</html>
diff --git a/docs/drvbhyve.rst b/docs/drvbhyve.rst
new file mode 100644
index 0000000000..95ef4e9b49
--- /dev/null
+++ b/docs/drvbhyve.rst
@@ -0,0 +1,582 @@
+.. role:: since
+
+============
+Bhyve driver
+============
+
+.. contents::
+
+Bhyve is a FreeBSD hypervisor. It first appeared in FreeBSD 10.0. However, it's
+recommended to keep tracking FreeBSD 10-STABLE to make sure all new features of
+bhyve are supported. In order to enable bhyve on your FreeBSD host, you'll need
+to load the ``vmm`` kernel module. Additionally, ``if_tap`` and ``if_bridge``
+modules should be loaded for networking support. Also, :since:`since 3.2.0` the
+``virt-host-validate(1)`` supports the bhyve host validation and could be used
+like this:
+
+::
+
+ $ virt-host-validate bhyve
+ BHYVE: Checking for vmm module : PASS
+ BHYVE: Checking for if_tap module : PASS
+ BHYVE: Checking for if_bridge module : PASS
+ BHYVE: Checking for nmdm module : PASS
+ $
+
+Additional information on bhyve could be obtained on
+`bhyve.org <https://bhyve.org/>`__.
+
+Connections to the Bhyve driver
+-------------------------------
+
+The libvirt bhyve driver is a single-instance privileged driver. Some sample
+connection URIs are:
+
+::
+
+ bhyve:///system (local access)
+ bhyve+unix:///system (local access)
+ bhyve+ssh://root@example.com/system (remote access, SSH tunnelled)
+
+Example guest domain XML configurations
+---------------------------------------
+
+Example config
+~~~~~~~~~~~~~~
+
+The bhyve driver in libvirt is in its early stage and under active development.
+So it supports only limited number of features bhyve provides.
+
+Note: in older libvirt versions, only a single network device and a single disk
+device were supported per-domain. However, :since:`since 1.2.6` the libvirt
+bhyve driver supports up to 31 PCI devices.
+
+Note: the Bhyve driver in libvirt will boot whichever device is first. If you
+want to install from CD, put the CD device first. If not, put the root HDD
+first.
+
+Note: Only the SATA bus is supported. Only ``cdrom``- and ``disk``-type disks
+are supported.
+
+::
+
+ <domain type='bhyve'>
+ <name>bhyve</name>
+ <uuid>df3be7e7-a104-11e3-aeb0-50e5492bd3dc</uuid>
+ <memory>219136</memory>
+ <currentMemory>219136</currentMemory>
+ <vcpu>1</vcpu>
+ <os>
+ <type>hvm</type>
+ </os>
+ <features>
+ <apic/>
+ <acpi/>
+ </features>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <disk type='file'>
+ <driver name='file' type='raw'/>
+ <source file='/path/to/bhyve_freebsd.img'/>
+ <target dev='hda' bus='sata'/>
+ </disk>
+ <disk type='file' device='cdrom'>
+ <driver name='file' type='raw'/>
+ <source file='/path/to/cdrom.iso'/>
+ <target dev='hdc' bus='sata'/>
+ <readonly/>
+ </disk>
+ <interface type='bridge'>
+ <model type='virtio'/>
+ <source bridge="virbr0"/>
+ </interface>
+ </devices>
+ </domain>
+
+(The <disk> sections may be swapped in order to install from *cdrom.iso*.)
+
+Example config (Linux guest)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note the addition of <bootloader>.
+
+::
+
+ <domain type='bhyve'>
+ <name>linux_guest</name>
+ <uuid>df3be7e7-a104-11e3-aeb0-50e5492bd3dc</uuid>
+ <memory>131072</memory>
+ <currentMemory>131072</currentMemory>
+ <vcpu>1</vcpu>
+ <bootloader>/usr/local/sbin/grub-bhyve</bootloader>
+ <os>
+ <type>hvm</type>
+ </os>
+ <features>
+ <apic/>
+ <acpi/>
+ </features>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <disk type='file' device='disk'>
+ <driver name='file' type='raw'/>
+ <source file='/path/to/guest_hdd.img'/>
+ <target dev='hda' bus='sata'/>
+ </disk>
+ <disk type='file' device='cdrom'>
+ <driver name='file' type='raw'/>
+ <source file='/path/to/cdrom.iso'/>
+ <target dev='hdc' bus='sata'/>
+ <readonly/>
+ </disk>
+ <interface type='bridge'>
+ <model type='virtio'/>
+ <source bridge="virbr0"/>
+ </interface>
+ </devices>
+ </domain>
+
+Example config (Linux UEFI guest, VNC, tablet)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an example to boot into Fedora 25 installation:
+
+::
+
+ <domain type='bhyve'>
+ <name>fedora_uefi_vnc_tablet</name>
+ <memory unit='G'>4</memory>
+ <vcpu>2</vcpu>
+ <os>
+ <type>hvm</type>
+ <loader readonly="yes"
type="pflash">/usr/local/share/uefi-firmware/BHYVE_UEFI.fd</loader>
+ </os>
+ <features>
+ <apic/>
+ <acpi/>
+ </features>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <disk type='file' device='cdrom'>
+ <driver name='file' type='raw'/>
+ <source
file='/path/to/Fedora-Workstation-Live-x86_64-25-1.3.iso'/>
+ <target dev='hdc' bus='sata'/>
+ <readonly/>
+ </disk>
+ <disk type='file' device='disk'>
+ <driver name='file' type='raw'/>
+ <source file='/path/to/linux_uefi.img'/>
+ <target dev='hda' bus='sata'/>
+ </disk>
+ <interface type='bridge'>
+ <model type='virtio'/>
+ <source bridge="virbr0"/>
+ </interface>
+ <serial type="nmdm">
+ <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/>
+ </serial>
+ <graphics type='vnc' port='5904'>
+ <listen type='address' address='127.0.0.1'/>
+ </graphics>
+ <controller type='usb' model='nec-xhci'/>
+ <input type='tablet' bus='usb'/>
+ </devices>
+ </domain>
+
+Please refer to the `UEFI <#uefi>`__ section for a more detailed explanation.
+
+Guest usage / management
+------------------------
+
+Connecting to a guest console
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Guest console connection is supported through the ``nmdm`` device. It could be
+enabled by adding the following to the domain XML ( :since:`Since 1.2.4` ):
+
+::
+
+ ...
+ <devices>
+ <serial type="nmdm">
+ <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/>
+ </serial>
+ </devices>
+ ...
+
+Make sure to load the ``nmdm`` kernel module if you plan to use that.
+
+Then ``virsh console`` command can be used to connect to the text console of a
+guest.
+
+**NB:** Some versions of bhyve have a bug that prevents guests from booting
+until the console is opened by a client. This bug was fixed in `FreeBSD
+changeset r262884 <https://svnweb.freebsd.org/changeset/base/262884>`__. If an
+older version is used, one either has to open a console manually with
+``virsh console`` to let a guest boot or start a guest using:
+
+::
+
+ start --console domname
+
+**NB:** A bootloader configured to require user interaction will prevent the
+domain from starting (and thus ``virsh console`` or ``start --console`` from
+functioning) until the user interacts with it manually on the VM host. Because
+users typically do not have access to the VM host, interactive bootloaders are
+unsupported by libvirt. *However,* if you happen to run into this scenario and
+also happen to have access to the Bhyve host machine, you may select a boot
+option and allow the domain to finish starting by using an alternative terminal
+client on the VM host to connect to the domain-configured null modem device. One
+example (assuming ``/dev/nmdm0B`` is configured as the slave end of the domain
+serial device) is:
+
+::
+
+ cu -l /dev/nmdm0B
+
+Converting from domain XML to Bhyve args
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-to-native`` command can preview the actual ``bhyve`` commands
+that will be executed for a given domain. It outputs two lines, the first line
+is a ``bhyveload`` command and the second is a ``bhyve`` command.
+
+Please note that the ``virsh domxml-to-native`` doesn't do any real actions
+other than printing the command, for example, it doesn't try to find a proper
+TAP interface and create it, like what is done when starting a domain; and
+always returns ``tap0`` for the network interface. So if you're going to run
+these commands manually, most likely you might want to tweak them.
+
+::
+
+ # virsh -c "bhyve:///system" domxml-to-native --format bhyve-argv --xml
/path/to/bhyve.xml
+ /usr/sbin/bhyveload -m 214 -d /home/user/vm1.img vm1
+ /usr/sbin/bhyve -c 2 -m 214 -A -I -H -P -s 0:0,hostbridge \
+ -s 3:0,virtio-net,tap0,mac=52:54:00:5d:74:e3 -s 2:0,virtio-blk,/home/user/vm1.img
\
+ -s 1,lpc -l com1,/dev/nmdm0A vm1
+
+Using ZFS volumes
+~~~~~~~~~~~~~~~~~
+
+It's possible to use ZFS volumes as disk devices :since:`since 1.2.8` . An
+example of domain XML device entry for that will look like:
+
+::
+
+ ...
+ <disk type='volume' device='disk'>
+ <source pool='zfspool' volume='vol1'/>
+ <target dev='vdb' bus='virtio'/>
+ </disk>
+ ...
+
+Please refer to the `Storage documentation <storage.html>`__ for more details on
+storage management.
+
+Using grub2-bhyve or Alternative Bootloaders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's possible to boot non-FreeBSD guests by specifying an explicit bootloader,
+e.g. ``grub-bhyve(1)``. Arguments to the bootloader may be specified as well. If
+the bootloader is ``grub-bhyve`` and arguments are omitted, libvirt will try and
+infer boot ordering from user-supplied <boot order='N'> configuration in
the
+domain. Failing that, it will boot the first disk in the domain (either
+``cdrom``- or ``disk``-type devices). If the disk type is ``disk``, it will
+attempt to boot from the first partition in the disk image.
+
+::
+
+ ...
+ <bootloader>/usr/local/sbin/grub-bhyve</bootloader>
+ <bootloader_args>...</bootloader_args>
+ ...
+
+Caveat: ``bootloader_args`` does not support any quoting. Filenames, etc, must
+not have spaces or they will be tokenized incorrectly.
+
+Using UEFI bootrom, VNC, and USB tablet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:since:`Since 3.2.0` , in addition to `grub-bhyve <#grubbhyve>`__, non-FreeBSD
+guests could be also booted using an UEFI boot ROM, provided both guest OS and
+installed ``bhyve(1)`` version support UEFI. To use that, ``loader`` should be
+specified in the ``os`` section:
+
+::
+
+ <domain type='bhyve'>
+ ...
+ <os>
+ <type>hvm</type>
+ <loader readonly="yes"
type="pflash">/usr/local/share/uefi-firmware/BHYVE_UEFI.fd</loader>
+ </os>
+ ...
+
+This uses the UEFI firmware provided by the
+`sysutils/bhyve-firmware <https://www.freshports.org/sysutils/bhyve-firmware/>`__
+FreeBSD port.
+
+VNC and the tablet input device could be configured this way:
+
+::
+
+ <domain type='bhyve'>
+ <devices>
+ ...
+ <graphics type='vnc' port='5904'>
+ <listen type='address' address='127.0.0.1'/>
+ </graphics>
+ <controller type='usb' model='nec-xhci'/>
+ <input type='tablet' bus='usb'/>
+ </devices>
+ ...
+ </domain>
+
+This way, VNC will be accessible on ``127.0.0.1:5904``.
+
+Please note that the tablet device requires to have a USB controller of the
+``nec-xhci`` model. Currently, only a single controller of this type and a
+single tablet are supported per domain.
+
+:since:`Since 3.5.0` , it's possible to configure how the video device is
+exposed to the guest using the ``vgaconf`` attribute:
+
+::
+
+ <domain type='bhyve'>
+ <devices>
+ ...
+ <graphics type='vnc' port='5904'>
+ <listen type='address' address='127.0.0.1'/>
+ </graphics>
+ <video>
+ <driver vgaconf='on'/>
+ <model type='gop' heads='1' primary='yes'/>
+ </video>
+ ...
+ </devices>
+ ...
+ </domain>
+
+If not specified, bhyve's default mode for ``vgaconf`` will be used. Please
+refer to the
+`bhyve(8)
<https://www.freebsd.org/cgi/man.cgi?query=bhyve&sektion=8&manpath...
+manual page and the `bhyve wiki <https://wiki.freebsd.org/bhyve>`__ for more
+details on using the ``vgaconf`` option.
+
+:since:`Since 3.7.0` , it's possible to use ``autoport`` to let libvirt allocate
+VNC port automatically (instead of explicitly specifying it with the ``port``
+attribute):
+
+::
+
+ <graphics type='vnc' autoport='yes'>
+
+:since:`Since 6.8.0` , it's possible to set framebuffer resolution using the
+``resolution`` sub-element:
+
+::
+
+ <video>
+ <model type='gop' heads='1' primary='yes'>
+ <resolution x='800' y='600'/>
+ </model>
+ </video>
+
+:since:`Since 6.8.0` , VNC server can be configured to use password based
+authentication:
+
+::
+
+ <graphics type='vnc' port='5904' passwd='foobar'>
+ <listen type='address' address='127.0.0.1'/>
+ </graphics>
+
+Note: VNC password authentication is known to be cryptographically weak.
+Additionally, the password is passed as a command line argument in clear text.
+Make sure you understand the risks associated with this feature before using it.
+
+Clock configuration
+~~~~~~~~~~~~~~~~~~~
+
+Originally bhyve supported only localtime for RTC. Support for UTC time was
+introduced in `FreeBSD changeset
+r284894 <https://svnweb.freebsd.org/changeset/base/284894>`__ for *10-STABLE*
+and in `changeset r279225 <https://svnweb.freebsd.org/changeset/base/279225>`__
+for *-CURRENT*. It's possible to use this in libvirt :since:`since 1.2.18` ,
+just place the following to domain XML:
+
+::
+
+ <domain type="bhyve">
+ ...
+ <clock offset='utc'/>
+ ...
+ </domain>
+
+Please note that if you run the older bhyve version that doesn't support UTC
+time, you'll fail to start a domain. As UTC is used as a default when you do not
+specify clock settings, you'll need to explicitly specify 'localtime' in
this
+case:
+
+::
+
+ <domain type="bhyve">
+ ...
+ <clock offset='localtime'/>
+ ...
+ </domain>
+
+e1000 NIC
+~~~~~~~~~
+
+As of `FreeBSD changeset
+r302504 <https://svnweb.freebsd.org/changeset/base/302504>`__ bhyve supports
+Intel e1000 network adapter emulation. It's supported in libvirt :since:`since
+3.1.0` and could be used as follows:
+
+::
+
+ ...
+ <interface type='bridge'>
+ <source bridge='virbr0'/>
+ <model type='e1000'/>
+ </interface>
+ ...
+
+Sound device
+~~~~~~~~~~~~
+
+As of `FreeBSD changeset
+r349355 <https://svnweb.freebsd.org/changeset/base/349355>`__ bhyve supports
+sound device emulation. It's supported in libvirt :since:`since 6.7.0` .
+
+::
+
+ ...
+ <sound model='ich7'>
+ <audio id='1'/>
+ </sound>
+ <audio id='1' type='oss'>
+ <input dev='/dev/dsp0'/>
+ <output dev='/dev/dsp0'/>
+ </audio>
+ ...
+
+Here, the ``sound`` element specifies the sound device as it's exposed to the
+guest, with ``ich7`` being the only supported model now, and the ``audio``
+element specifies how the guest device is mapped to the host sound device.
+
+Virtio-9p filesystem
+~~~~~~~~~~~~~~~~~~~~
+
+As of `FreeBSD changeset
+r366413 <https://svnweb.freebsd.org/changeset/base/366413>`__ bhyve supports
+sharing arbitrary directory tree between the guest and the host. It's supported
+in libvirt :since:`since 6.9.0` .
+
+::
+
+ ...
+ <filesystem>
+ <source dir='/shared/dir'/>
+ <target dir='shared_dir'/>
+ </filesystem>
+ ...
+
+This share could be made read only by adding the ``<readonly/>`` sub-element.
+
+In the Linux guest, this could be mounted using:
+
+::
+
+ mount -t 9p shared_dir /mnt/shared_dir
+
+Wiring guest memory
+~~~~~~~~~~~~~~~~~~~
+
+:since:`Since 4.4.0` , it's possible to specify that guest memory should be
+wired and cannot be swapped out as follows:
+
+::
+
+ <domain type="bhyve">
+ ...
+ <memoryBacking>
+ <locked/>
+ </memoryBacking>
+ ...
+ </domain>
+
+CPU topology
+~~~~~~~~~~~~
+
+:since:`Since 4.5.0` , it's possible to specify guest CPU topology, if bhyve
+supports that. Support for specifying guest CPU topology was added to bhyve in
+`FreeBSD changeset r332298 <https://svnweb.freebsd.org/changeset/base/332298>`__
+for *-CURRENT*. Example:
+
+::
+
+ <domain type="bhyve">
+ ...
+ <cpu>
+ <topology sockets='1' cores='2' threads='1'/>
+ </cpu>
+ ...
+ </domain>
+
+Ignoring unknown MSRs reads and writes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:since:`Since 5.1.0` , it's possible to make bhyve ignore accesses to
+unimplemented Model Specific Registers (MSRs). Example:
+
+::
+
+ <domain type="bhyve">
+ ...
+ <features>
+ ...
+ <msrs unknown='ignore'/>
+ ...
+ </features>
+ ...
+ </domain>
+
+Pass-through of arbitrary bhyve commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:since:`Since 5.1.0` , it's possible to pass additional command-line arguments
+to the bhyve process when starting the domain using the ``<bhyve:commandline>``
+element under ``domain``. To supply an argument, use the element ``<bhyve:arg>``
+with the attribute ``value`` set to additional argument to be added. The arg
+element may be repeated multiple times. To use this XML addition, it is
+necessary to issue an XML namespace request (the special ``xmlns:name``
+attribute) that pulls in ``http://libvirt.org/schemas/domain/bhyve/1.0``;
+typically, the namespace is given the name of ``bhyve``.
+
+Example:
+
+::
+
+ <domain type="bhyve"
xmlns:bhyve="http://libvirt.org/schemas/domain/bhyve/1.0">
+ ...
+ <bhyve:commandline>
+ <bhyve:arg value='-somebhyvearg'/>
+ </bhyve:commandline>
+ </domain>
+
+Note that these extensions are for testing and development purposes only. They
+are **unsupported**, using them may result in inconsistent state, and upgrading
+either bhyve or libvirtd maybe break behavior of a domain that was relying on a
+specific commands pass-through.
diff --git a/docs/meson.build b/docs/meson.build
index bb7e27e031..a6c3077f25 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvbhyve',
'drvesx',
'drvhyperv',
'drvlxc',
@@ -79,6 +78,7 @@ docs_rst_files = [
'daemons',
'downloads',
'drivers',
+ 'drvbhyve',
'drvch',
'drvqemu',
'errors',
--
2.35.1
6:42 a.m.
New subject: [PATCH 03/29] docs: Convert 'drvbhyve' page to rST
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 a.m.
New subject: [PATCH 04/29] docs: Convert 'drvesx' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvesx.html.in | 838 --------------------------------------------
docs/drvesx.rst | 681 +++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 682 insertions(+), 839 deletions(-)
delete mode 100644 docs/drvesx.html.in
create mode 100644 docs/drvesx.rst
diff --git a/docs/drvesx.html.in b/docs/drvesx.html.in
deleted file mode 100644
index c56da16f57..0000000000
--- a/docs/drvesx.html.in
+++ /dev/null
@@ -1,838 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>VMware ESX hypervisor driver</h1>
- <ul id="toc"></ul>
- <p>
- The libvirt VMware ESX driver can manage VMware ESX/ESXi 3.5/4.x/5.x and
- VMware GSX 2.0, also called VMware Server 2.0, and possibly later
- versions. <span class="since">Since 0.8.3</span> the driver
can also
- connect to a VMware vCenter 2.5/4.x/5.x (VPX).
- </p>
-
- <h2><a id="project">Project Links</a></h2>
-
- <ul>
- <li>
- The <a href="https://www.vmware.com/">VMware ESX and
GSX</a>
- hypervisors
- </li>
- </ul>
-
- <h2><a id="prereq">Deployment
pre-requisites</a></h2>
- <p>
- None. Any out-of-the-box installation of VPX/ESX(i)/GSX should work. No
- preparations are required on the server side, no libvirtd must be
- installed on the ESX server. The driver uses version 2.5 of the remote,
- SOAP based
- <a
href="https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/Re...
- VMware Virtual Infrastructure API</a> (VI API) to communicate with the
- ESX server, like the VMware Virtual Infrastructure Client (VI client)
- does. Since version 4.0 this API is called
- <a
href="https://www.vmware.com/support/developer/vc-sdk/visdk400pubs/R...
- VMware vSphere API</a>.
- </p>
-
- <h2><a id="uri">Connections to the VMware ESX
driver</a></h2>
- <p>
- Some example remote connection URIs for the driver are:
- </p>
-<pre>
-vpx://example-vcenter.com/dc1/srv1 (VPX over HTTPS, select ESX server 'srv1'
in datacenter 'dc1')
-esx://example-esx.com (ESX over HTTPS)
-gsx://example-gsx.com (GSX over HTTPS)
-esx://example-esx.com/?transport=http (ESX over HTTP)
-esx://example-esx.com/?no_verify=1 (ESX over HTTPS, but doesn't verify the
server's SSL certificate)
-</pre>
- <p>
- <strong>Note</strong>: In contrast to other drivers, the ESX driver
is
- a client-side-only driver. It connects to the ESX server using HTTP(S).
- Therefore, the <a href="remote.html">remote transport
mechanism</a>
- provided by the remote driver and libvirtd will not work, and you
- cannot use URIs like <code>esx+ssh://example.com</code>.
- </p>
-
-
- <h3><a id="uriformat">URI Format</a></h3>
- <p>
- URIs have this general form (<code>[...]</code> marks an optional
part).
- </p>
-<pre>
-type://[username@]hostname[:port]/[[folder/...]datacenter/[folder/...][cluster/]server][?extraparameters]
-</pre>
- <p>
- The <code>type://</code> is either <code>esx://</code>
or
- <code>gsx://</code> or <code>vpx://</code> <span
class="since">since 0.8.3</span>.
- The driver selects the default port depending on the
<code>type://</code>.
- For <code>esx://</code> and <code>vpx://</code> the
default HTTPS port
- is 443, for <code>gsx://</code> it is 8333.
- If the port parameter is given, it overrides the default port.
- </p>
- <p>
- A <code>vpx://</code> connection is currently restricted to a single
- ESX server. This might be relaxed in the future. The path part of the
- URI is used to specify the datacenter and the ESX server in it. If the
- ESX server is part of a cluster then the cluster has to be specified too.
- </p>
- <p>
- An example: ESX server <code>example-esx.com</code> is managed by
- vCenter <code>example-vcenter.com</code> and part of cluster
- <code>cluster1</code>. This cluster is part of datacenter
<code>dc1</code>.
- </p>
-<pre>
-vpx://example-vcenter.com/dc1/cluster1/example-esx.com
-</pre>
- <p>
- Datacenters and clusters can be organized in folders, those have to be
- specified as well. The driver can handle folders
- <span class="since">since 0.9.7</span>.
- </p>
-<pre>
-vpx://example-vcenter.com/folder1/dc1/folder2/example-esx.com
-</pre>
-
-
- <h4><a id="extraparams">Extra parameters</a></h4>
- <p>
- Extra parameters can be added to a URI as part of the query string
- (the part following <code>?</code>). A single parameter is formed by
a
- <code>name=value</code> pair. Multiple parameters are separated by
- <code>&</code>.
- </p>
-<pre>
-?<span style="color: #E50000">no_verify=1</span>&<span
style="color: #00B200">auto_answer=1</span>&<span
style="color: #0000E5">proxy=socks://example-proxy.com:23456</span>
-</pre>
- <p>
- The driver understands the extra parameters shown below.
- </p>
- <table class="top_table">
- <tr>
- <th>Name</th>
- <th>Values</th>
- <th>Meaning</th>
- </tr>
- <tr>
- <td>
- <code>transport</code>
- </td>
- <td>
- <code>http</code> or <code>https</code>
- </td>
- <td>
- Overrides the default HTTPS transport. For
<code>esx://</code>
- and <code>vpx://</code> the default HTTP port is 80, for
- <code>gsx://</code> it is 8222.
- </td>
- </tr>
- <tr>
- <td>
- <code>vcenter</code>
- </td>
- <td>
- Hostname of a VMware vCenter or <code>*</code>
- </td>
- <td>
- In order to perform a migration the driver needs to know the
- VMware vCenter for the ESX server. If set to <code>*</code>,
- the driver connects to the vCenter known to the ESX server.
- This parameter in useful when connecting to an ESX server only.
- </td>
- </tr>
- <tr>
- <td>
- <code>no_verify</code>
- </td>
- <td>
- <code>0</code> or <code>1</code>
- </td>
- <td>
- If set to 1, this disables libcurl client checks of the server's
- SSL certificate. The default value is 0. See the
- <a href="#certificates">Certificates for HTTPS</a>
section for
- details.
- </td>
- </tr>
- <tr>
- <td>
- <code>auto_answer</code>
- </td>
- <td>
- <code>0</code> or <code>1</code>
- </td>
- <td>
- If set to 1, the driver answers all
- <a href="#questions">questions</a> with the default
answer.
- If set to 0, questions are reported as errors. The default
- value is 0. <span class="since">Since
0.7.5</span>.
- </td>
- </tr>
- <tr>
- <td>
- <code>proxy</code>
- </td>
- <td>
- <code>[type://]hostname[:port]</code>
- </td>
- <td>
- Allows to specify a proxy for HTTP and HTTPS communication.
- <span class="since">Since 0.8.2</span>.
- The optional <code>type</code> part may be one of:
- <code>http</code>, <code>socks</code>,
<code>socks4</code>,
- <code>socks4a</code> or <code>socks5</code>. The
default is
- <code>http</code> and <code>socks</code> is
synonymous for
- <code>socks5</code>. The optional
<code>port</code> allows to
- override the default port 1080.
- </td>
- </tr>
- </table>
-
-
- <h3><a id="auth">Authentication</a></h3>
- <p>
- In order to perform any useful operation the driver needs to log into
- the ESX server. Therefore, only <code>virConnectOpenAuth</code> can
be
- used to connect to an ESX server, <code>virConnectOpen</code> and
- <code>virConnectOpenReadOnly</code> don't work.
- To log into an ESX server or vCenter the driver will request
- credentials using the callback passed to the
- <code>virConnectOpenAuth</code> function. The driver passes the
- hostname as challenge parameter to the callback. This enables the
- callback to distinguish between requests for ESX server and vCenter.
- </p>
- <p>
- <strong>Note</strong>: During the ongoing driver development,
testing
- is done using an unrestricted <code>root</code> account. Problems
may
- occur if you use a restricted account. Detailed testing with restricted
- accounts has not been done yet.
- </p>
-
-
- <h3><a id="certificates">Certificates for
HTTPS</a></h3>
- <p>
- By default the ESX driver uses HTTPS to communicate with an ESX server.
- Proper HTTPS communication requires correctly configured SSL
- certificates. This certificates are different from the ones libvirt
- uses for <a href="remote.html">secure communication over
TLS</a> to a
- libvirtd one a remote server.
- </p>
- <p>
- By default the driver tries to verify the server's SSL certificate
- using the CA certificate pool installed on your client computer. With
- an out-of-the-box installed ESX server this won't work, because a newly
- installed ESX server uses auto-generated self-signed certificates.
- Those are signed by a CA certificate that is typically not known to your
- client computer and libvirt will report an error like this one:
- </p>
-<pre>
-error: internal error curl_easy_perform() returned an error: Peer certificate cannot be
authenticated with known CA certificates (60)
-</pre>
- <p>
- Where are two ways to solve this problem:
- </p>
- <ul>
- <li>
- Use the <code>no_verify=1</code> <a
href="#extraparams">extra parameter</a>
- to disable server certificate verification.
- </li>
- <li>
- Generate new SSL certificates signed by a CA known to your client
- computer and replace the original ones on your ESX server. See the
- section <i>Replace a Default Certificate with a CA-Signed
Certificate</i>
- in the <a
href="https://www.vmware.com/pdf/vsphere4/r40/vsp_40_esx_server_conf...
Configuration Guide</a>
- </li>
- </ul>
-
-
- <h3><a id="connproblems">Connection
problems</a></h3>
- <p>
- There are also other causes for connection problems than the
- <a href="#certificates">HTTPS certificate</a> related
ones.
- </p>
- <ul>
- <li>
- As stated before the ESX driver doesn't need the
- <a href="remote.html">remote transport mechanism</a>
- provided by the remote driver and libvirtd, nor does the ESX driver
- support it. Therefore, using an URI including a transport in the
- scheme won't work. Only <a href="#uriformat">URIs as
described</a>
- are supported by the ESX driver. Here's a collection of possible
- error messages:
-<pre>
-$ virsh -c esx+tcp://example.com/
-error: unable to connect to libvirtd at 'example.com': Connection refused
-</pre>
-<pre>
-$ virsh -c esx+tls://example.com/
-error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or
directory
-</pre>
-<pre>
-$ virsh -c esx+ssh://example.com/
-error: cannot recv data: ssh: connect to host example.com port 22: Connection refused
-</pre>
-<pre>
-$ virsh -c esx+ssh://example.com/
-error: cannot recv data: Resource temporarily unavailable
-</pre>
- </li>
- <li>
- <span class="since">Since 0.7.0</span> libvirt contains
the ESX
- driver. Earlier versions of libvirt will report a misleading error
- about missing certificates when you try to connect to an ESX server.
-<pre>
-$ virsh -c esx://example.com/
-error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or
directory
-</pre>
- <p>
- Don't let this error message confuse you. Setting up certificates
- as described on the <a
href="remote.html#Remote_certificates">remote transport mechanism</a>
page
- does not help, as this is not a certificate related problem.
- </p>
- <p>
- To fix this problem you need to update your libvirt to 0.7.0 or newer.
- You may also see this error when you use a libvirt version that
- contains the ESX driver but you or your distro disabled the ESX
- driver during compilation. <span class="since">Since
0.8.3</span>
- the error message has been improved in this case:
- </p>
-<pre>
-$ virsh -c esx://example.com/
-error: invalid argument in libvirt was built without the 'esx' driver
-</pre>
- </li>
- </ul>
-
-
- <h2><a id="questions">Questions blocking
tasks</a></h2>
- <p>
- Some methods of the VI API start tasks, for example
- <code>PowerOnVM_Task()</code>. Such tasks may be blocked by
questions
- if the ESX server detects an issue with the domain that requires user
- interaction. The ESX driver cannot prompt the user to answer a
- question, libvirt doesn't have an API for something like this.
- </p>
- <p>
- The VI API provides the <code>AnswerVM()</code> method to
- programmatically answer a questions. So the driver has two options
- how to handle such a situation: either answer the questions with the
- default answer or report the question as an error and cancel the
- blocked task if possible. The
- <a
href="#uriformat"><code>auto_answer</code></a> query
parameter
- controls the answering behavior.
- </p>
-
-
- <h2><a id="xmlspecial">Specialities in the domain XML
config</a></h2>
- <p>
- There are several specialities in the domain XML config for ESX domains.
- </p>
-
- <h3><a id="restrictions">Restrictions</a></h3>
- <p>
- There are some restrictions for some values of the domain XML config.
- The driver will complain if this restrictions are violated.
- </p>
- <ul>
- <li>
- Memory size has to be a multiple of 4096
- </li>
- <li>
- Number of virtual CPU has to be 1 or a multiple of 2.
- <span class="since">Since 4.10.0</span> any number of
vCPUs is
- supported.
- </li>
- <li>
- Valid MAC address prefixes are <code>00:0c:29</code> and
- <code>00:50:56</code>. <span class="since">Since
0.7.6</span>
- arbitrary <a href="#macaddresses">MAC addresses</a> are
supported.
- </li>
- </ul>
-
-
- <h3><a id="datastore">Datastore
references</a></h3>
- <p>
- Storage is managed in datastores. VMware uses a special path format to
- reference files in a datastore. Basically, the datastore name is put
- into squared braces in front of the path.
- </p>
-<pre>
-[datastore] directory/filename
-</pre>
- <p>
- To define a new domain the driver converts the domain XML into a
- VMware VMX file and uploads it to a datastore known to the ESX server.
- Because multiple datastores may be known to an ESX server the driver
- needs to decide to which datastore the VMX file should be uploaded.
- The driver deduces this information from the path of the source of the
- first file-based harddisk listed in the domain XML.
- </p>
-
-
- <h3><a id="macaddresses">MAC addresses</a></h3>
- <p>
- VMware has registered two MAC address prefixes for domains:
- <code>00:0c:29</code> and <code>00:50:56</code>. These
prefixes are
- split into ranges for different purposes.
- </p>
- <table class="top_table">
- <tr>
- <th>Range</th>
- <th>Purpose</th>
- </tr>
- <tr>
- <td>
- <code>00:0c:29:00:00:00</code> -
<code>00:0c:29:ff:ff:ff</code>
- </td>
- <td>
- An ESX server autogenerates MAC addresses from this range if
- the VMX file doesn't contain a MAC address when trying to start
- a domain.
- </td>
- </tr>
- <tr>
- <td>
- <code>00:50:56:00:00:00</code> -
<code>00:50:56:3f:ff:ff</code>
- </td>
- <td>
- MAC addresses from this range can by manually assigned by the
- user in the VI client.
- </td>
- </tr>
- <tr>
- <td>
- <code>00:50:56:80:00:00</code> -
<code>00:50:56:bf:ff:ff</code>
- </td>
- <td>
- A VI client autogenerates MAC addresses from this range for
- newly defined domains.
- </td>
- </tr>
- </table>
- <p>
- The VMX files generated by the ESX driver always contain a MAC address,
- because libvirt generates a random one if an interface element in the
- domain XML file lacks a MAC address.
- <span class="since">Since 0.7.6</span> the ESX driver sets
the prefix
- for generated MAC addresses to <code>00:0c:29</code>. Before 0.7.6
- the <code>00:50:56</code> prefix was used. Sometimes this resulted
in
- the generation of out-of-range MAC address that were rejected by the
- ESX server.
- </p>
- <p>
- Also <span class="since">since 0.7.6</span> every MAC
address outside
- this ranges can be used. For such MAC addresses the ESX server-side
- check is disabled in the VMX file to stop the ESX server from rejecting
- out-of-predefined-range MAC addresses.
- </p>
-<pre>
-ethernet0.checkMACAddress = "false"
-</pre>
- <p>
- <span class="since">Since 6.6.0</span>, one can force
libvirt to keep the
- provided MAC address when it's in the reserved VMware range by adding a
- <code>type="static"</code> attribute to the
<code><mac/></code> element.
- Note that this attribute is useless if the provided MAC address is outside of
- the reserved VMWare ranges.
- </p>
-
-
- <h3><a id="hardware">Available hardware</a></h3>
- <p>
- VMware ESX supports different models of SCSI controllers and network
- cards.
- </p>
-
- <h4>SCSI controller models</h4>
- <dl>
- <dt><code>auto</code></dt>
- <dd>
- This isn't an actual controller model. If specified the ESX driver
- tries to detect the SCSI controller model referenced in the
- <code>.vmdk</code> file and use it. Autodetection fails when a
- SCSI controller has multiple disks attached and the SCSI controller
- models referenced in the <code>.vmdk</code> files are
inconsistent.
- <span class="since">Since 0.8.3</span>
- </dd>
- <dt><code>buslogic</code></dt>
- <dd>
- BusLogic SCSI controller for older guests.
- </dd>
- <dt><code>lsilogic</code></dt>
- <dd>
- LSI Logic SCSI controller for recent guests.
- </dd>
- <dt><code>lsisas1068</code></dt>
- <dd>
- LSI Logic SAS 1068 controller. <span class="since">Since
0.8.0</span>
- </dd>
- <dt><code>vmpvscsi</code></dt>
- <dd>
- Special VMware Paravirtual SCSI controller, requires VMware tools inside
- the guest. See <a
href="https://kb.vmware.com/kb/1010398">VMware KB1010398</a>
- for details. <span class="since">Since 0.8.3</span>
- </dd>
- </dl>
- <p>
- Here a domain XML snippet:
- </p>
-<pre>
-...
-<disk type='file' device='disk'>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='0' bus='0'
unit='0'/>
-</disk>
-<controller type='scsi' index='0'
model='<strong>lsilogic</strong>'/>
-...
-</pre>
- <p>
- The controller element is supported <span class="since">since
0.8.2</span>.
- Prior to this <code><driver
name='lsilogic'/></code> was abused to
- specify the SCSI controller model. This attribute usage is deprecated now.
- </p>
-<pre>
-...
-<disk type='file' device='disk'>
- <driver name='<strong>lsilogic</strong>'/>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
-</disk>
-...
-</pre>
-
-
- <h4>Network card models</h4>
- <dl>
- <dt><code>vlance</code></dt>
- <dd>
- AMD PCnet32 network card for older guests.
- </dd>
- <dt><code>vmxnet</code>, <code>vmxnet2</code>,
<code>vmxnet3</code></dt>
- <dd>
- Special VMware VMXnet network card, requires VMware tools inside
- the guest. See <a
href="https://kb.vmware.com/kb/1001805">VMware KB1001805</a>
- for details.
- </dd>
- <dt><code>e1000</code></dt>
- <dd>
- Intel E1000 network card for recent guests.
- </dd>
- </dl>
- <p>
- Here a domain XML snippet:
- </p>
-<pre>
-...
-<interface type='bridge'>
- <mac address='00:50:56:25:48:c7'/>
- <source bridge='VM Network'/>
- <model type='<strong>e1000</strong>'/>
-</interface>
-...
-</pre>
-
-
- <h2><a id="importexport">Import and export of domain XML
configs</a></h2>
- <p>
- The ESX driver currently supports a native config format known as
- <code>vmware-vmx</code> to handle VMware VMX configs.
- </p>
-
-
- <h3><a id="xmlimport">Converting from VMware VMX config to
domain XML config</a></h3>
- <p>
- The <code>virsh domxml-from-native</code> provides a way to convert
an
- existing VMware VMX config into a domain XML config that can then be
- used by libvirt.
- </p>
-<pre>
-$ cat > demo.vmx << EOF
-#!/usr/bin/vmware
-config.version = "8"
-virtualHW.version = "4"
-floppy0.present = "false"
-nvram = "Fedora11.nvram"
-deploymentPlatform = "windows"
-virtualHW.productCompatibility = "hosted"
-tools.upgrade.policy = "useGlobal"
-powerType.powerOff = "default"
-powerType.powerOn = "default"
-powerType.suspend = "default"
-powerType.reset = "default"
-displayName = "Fedora11"
-extendedConfigFile = "Fedora11.vmxf"
-scsi0.present = "true"
-scsi0.sharedBus = "none"
-scsi0.virtualDev = "lsilogic"
-memsize = "1024"
-scsi0:0.present = "true"
-scsi0:0.fileName =
"/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11.vmdk"
-scsi0:0.deviceType = "scsi-hardDisk"
-ide0:0.present = "true"
-ide0:0.clientDevice = "true"
-ide0:0.deviceType = "cdrom-raw"
-ide0:0.startConnected = "false"
-ethernet0.present = "true"
-ethernet0.networkName = "VM Network"
-ethernet0.addressType = "vpx"
-ethernet0.generatedAddress = "00:50:56:91:48:c7"
-chipset.onlineStandby = "false"
-guestOSAltName = "Red Hat Enterprise Linux 5 (32-Bit)"
-guestOS = "rhel5"
-uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
-snapshot.action = "keep"
-sched.cpu.min = "0"
-sched.cpu.units = "mhz"
-sched.cpu.shares = "normal"
-sched.mem.minsize = "0"
-sched.mem.shares = "normal"
-toolScripts.afterPowerOn = "true"
-toolScripts.afterResume = "true"
-toolScripts.beforeSuspend = "true"
-toolScripts.beforePowerOff = "true"
-scsi0:0.redo = ""
-tools.syncTime = "false"
-uuid.location = "56 4d b5 06 a2 bd fb eb-ae 86 f7 d8 49 27 d0 c4"
-sched.cpu.max = "unlimited"
-sched.swap.derivedName =
"/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11-7de040d8.vswp"
-tools.remindInstall = "TRUE"
-EOF
-
-$ virsh -c esx://example.com domxml-from-native vmware-vmx demo.vmx
-Enter username for example.com [root]:
-Enter root password for example.com:
-<domain type='vmware'>
- <name>Fedora11</name>
- <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
- <memory>1048576</memory>
- <currentMemory>1048576</currentMemory>
- <vcpu>1</vcpu>
- <os>
- <type arch='i686'>hvm</type>
- </os>
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>destroy</on_crash>
- <devices>
- <disk type='file' device='disk'>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='0' bus='0'
unit='0'/>
- </disk>
- <controller type='scsi' index='0'
model='lsilogic'/>
- <interface type='bridge'>
- <mac address='00:50:56:91:48:c7'/>
- <source bridge='VM Network'/>
- </interface>
- </devices>
-</domain>
-</pre>
-
-
- <h3><a id="xmlexport">Converting from domain XML config to
VMware VMX config</a></h3>
- <p>
- The <code>virsh domxml-to-native</code> provides a way to convert a
- domain XML config into a VMware VMX config.
- </p>
-<pre>
-$ cat > demo.xml << EOF
-<domain type='vmware'>
- <name>Fedora11</name>
- <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
- <memory>1048576</memory>
- <currentMemory>1048576</currentMemory>
- <vcpu>1</vcpu>
- <os>
- <type arch='x86_64'>hvm</type>
- </os>
- <devices>
- <disk type='file' device='disk'>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='0' bus='0'
unit='0'/>
- </disk>
- <controller type='scsi' index='0'
model='lsilogic'/>
- <interface type='bridge'>
- <mac address='00:50:56:25:48:c7'/>
- <source bridge='VM Network'/>
- </interface>
- </devices>
-</domain>
-EOF
-
-$ virsh -c esx://example.com domxml-to-native vmware-vmx demo.xml
-Enter username for example.com [root]:
-Enter root password for example.com:
-config.version = "8"
-virtualHW.version = "4"
-guestOS = "other-64"
-uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
-displayName = "Fedora11"
-memsize = "1024"
-numvcpus = "1"
-scsi0.present = "true"
-scsi0.virtualDev = "lsilogic"
-scsi0:0.present = "true"
-scsi0:0.deviceType = "scsi-hardDisk"
-scsi0:0.fileName = "/vmfs/volumes/local-storage/Fedora11/Fedora11.vmdk"
-ethernet0.present = "true"
-ethernet0.networkName = "VM Network"
-ethernet0.connectionType = "bridged"
-ethernet0.addressType = "static"
-ethernet0.address = "00:50:56:25:48:C7"
-</pre>
-
-
- <h2><a id="xmlconfig">Example domain XML
configs</a></h2>
-
- <h3>Fedora11 on x86_64</h3>
-<pre>
-<domain type='vmware'>
- <name>Fedora11</name>
- <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
- <memory>1048576</memory>
- <currentMemory>1048576</currentMemory>
- <vcpu>1</vcpu>
- <os>
- <type arch='x86_64'>hvm</type>
- </os>
- <devices>
- <disk type='file' device='disk'>
- <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='0' bus='0'
unit='0'/>
- </disk>
- <controller type='scsi' index='0'/>
- <interface type='bridge'>
- <mac address='00:50:56:25:48:c7'/>
- <source bridge='VM Network'/>
- </interface>
- </devices>
-</domain>
-</pre>
-
-
- <h2><a id="migration">Migration</a></h2>
- <p>
- A migration cannot be initiated on an ESX server directly, a VMware
- vCenter is necessary for this. The <code>vcenter</code> query
- parameter must be set either to the hostname or IP address of the
- vCenter managing the ESX server or to <code>*</code>. Setting it
- to <code>*</code> causes the driver to connect to the vCenter known
to
- the ESX server. If the ESX server is not managed by a vCenter an error
- is reported.
- </p>
-<pre>
-esx://example.com/?vcenter=example-vcenter.com
-</pre>
- <p>
- Here's an example how to migrate the domain <code>Fedora11</code>
from
- ESX server <code>example-src.com</code> to ESX server
- <code>example-dst.com</code> implicitly involving vCenter
- <code>example-vcenter.com</code> using
<code>virsh</code>.
- </p>
-<pre>
-$ virsh -c esx://example-src.com/?vcenter=* migrate Fedora11
esx://example-dst.com/?vcenter=*
-Enter username for example-src.com [root]:
-Enter root password for example-src.com:
-Enter username for example-vcenter.com [administrator]:
-Enter administrator password for example-vcenter.com:
-Enter username for example-dst.com [root]:
-Enter root password for example-dst.com:
-Enter username for example-vcenter.com [administrator]:
-Enter administrator password for example-vcenter.com:
-</pre>
- <p>
- <span class="since">Since 0.8.3</span> you can directly
connect to a vCenter.
- This simplifies migration a bit. Here's the same migration as above but
- using <code>vpx://</code> connections and assuming both ESX server
are in
- datacenter <code>dc1</code> and aren't part of a cluster.
- </p>
-<pre>
-$ virsh -c vpx://example-vcenter.com/dc1/example-src.com migrate Fedora11
vpx://example-vcenter.com/dc1/example-dst.com
-Enter username for example-vcenter.com [administrator]:
-Enter administrator password for example-vcenter.com:
-Enter username for example-vcenter.com [administrator]:
-Enter administrator password for example-vcenter.com:
-</pre>
-
-
- <h2><a id="scheduler">Scheduler
configuration</a></h2>
- <p>
- The driver exposes the ESX CPU scheduler. The parameters listed below
- are available to control the scheduler.
- </p>
- <dl>
- <dt><code>reservation</code></dt>
- <dd>
- The amount of CPU resource in MHz that is guaranteed to be
- available to the domain. Valid values are 0 and greater.
- </dd>
- <dt><code>limit</code></dt>
- <dd>
- The CPU utilization of the domain will be
- limited to this value in MHz, even if more CPU resources are
- available. If the limit is set to -1, the CPU utilization of the
- domain is unlimited. If the limit is not set to -1, it must be
- greater than or equal to the reservation.
- </dd>
- <dt><code>shares</code></dt>
- <dd>
- Shares are used to determine relative CPU
- allocation between domains. In general, a domain with more shares
- gets proportionally more of the CPU resource. Valid values are 0
- and greater. The special values -1, -2 and -3 represent the
- predefined shares level <code>low</code>,
<code>normal</code> and
- <code>high</code>.
- </dd>
- </dl>
-
-
- <h2><a id="tools">VMware tools</a></h2>
- <p>
- Some actions require installed VMware tools. If the VMware tools are
- not installed in the guest and one of the actions below is to be
- performed the ESX server raises an error and the driver reports it.
- </p>
- <ul>
- <li>
- <code>virDomainGetHostname</code>
- </li>
- <li>
- <code>virDomainInterfaceAddresses</code> (only for the
- <code>VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT</code> source)
- </li>
- <li>
- <code>virDomainReboot</code>
- </li>
- <li>
- <code>virDomainShutdown</code>
- </li>
- </ul>
-
-
- <h2><a id="links">Links</a></h2>
- <ul>
- <li>
- <a href="https://www.vmware.com/support/developer/vc-sdk/">
- VMware vSphere Web Services SDK Documentation
- </a>
- </li>
- <li>
- <a href="https://www.vmware.com/pdf/esx3_memory.pdf">
- The Role of Memory in VMware ESX Server 3
- </a>
- </li>
- <li>
- <a href="https://www.sanbarrow.com/vmx.html">
- VMware VMX config parameters
- </a>
- </li>
- <li>
- <a href="https://www.vmware.com/pdf/vsp_4_pvscsi_perf.pdf">
- VMware ESX 4.0 PVSCSI Storage Performance
- </a>
- </li>
- </ul>
-</body></html>
diff --git a/docs/drvesx.rst b/docs/drvesx.rst
new file mode 100644
index 0000000000..7b35492d21
--- /dev/null
+++ b/docs/drvesx.rst
@@ -0,0 +1,681 @@
+.. role:: since
+
+============================
+VMware ESX hypervisor driver
+============================
+
+.. contents::
+
+The libvirt VMware ESX driver can manage VMware ESX/ESXi 3.5/4.x/5.x and VMware
+GSX 2.0, also called VMware Server 2.0, and possibly later versions.
+:since:`Since 0.8.3` the driver can also connect to a VMware vCenter 2.5/4.x/5.x
+(VPX).
+
+Project Links
+-------------
+
+- The `VMware ESX and GSX <https://www.vmware.com/>`__ hypervisors
+
+Deployment pre-requisites
+-------------------------
+
+None. Any out-of-the-box installation of VPX/ESX(i)/GSX should work. No
+preparations are required on the server side, no libvirtd must be installed on
+the ESX server. The driver uses version 2.5 of the remote, SOAP based `VMware
+Virtual Infrastructure
+API
<https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuid...
+(VI API) to communicate with the ESX server, like the VMware Virtual
+Infrastructure Client (VI client) does. Since version 4.0 this API is called
+`VMware vSphere
+API
<https://www.vmware.com/support/developer/vc-sdk/visdk400pubs/ReferenceGui....
+
+Connections to the VMware ESX driver
+------------------------------------
+
+Some example remote connection URIs for the driver are:
+
+::
+
+ vpx://example-vcenter.com/dc1/srv1 (VPX over HTTPS, select ESX server
'srv1' in datacenter 'dc1')
+ esx://example-esx.com (ESX over HTTPS)
+ gsx://example-gsx.com (GSX over HTTPS)
+ esx://example-esx.com/?transport=http (ESX over HTTP)
+ esx://example-esx.com/?no_verify=1 (ESX over HTTPS, but doesn't verify the
server's SSL certificate)
+
+**Note**: In contrast to other drivers, the ESX driver is a client-side-only
+driver. It connects to the ESX server using HTTP(S). Therefore, the `remote
+transport mechanism <remote.html>`__ provided by the remote driver and libvirtd
+will not work, and you cannot use URIs like ``esx+ssh://example.com``.
+
+URI Format
+~~~~~~~~~~
+
+URIs have this general form (``[...]`` marks an optional part).
+
+::
+
+
type://[username@]hostname[:port]/[[folder/...]datacenter/[folder/...][cluster/]server][?extraparameters]
+
+The ``type://`` is either ``esx://`` or ``gsx://`` or ``vpx://`` :since:`since
+0.8.3` . The driver selects the default port depending on the ``type://``. For
+``esx://`` and ``vpx://`` the default HTTPS port is 443, for ``gsx://`` it is
+8333. If the port parameter is given, it overrides the default port.
+
+A ``vpx://`` connection is currently restricted to a single ESX server. This
+might be relaxed in the future. The path part of the URI is used to specify the
+datacenter and the ESX server in it. If the ESX server is part of a cluster then
+the cluster has to be specified too.
+
+An example: ESX server ``example-esx.com`` is managed by vCenter
+``example-vcenter.com`` and part of cluster ``cluster1``. This cluster is part
+of datacenter ``dc1``.
+
+::
+
+ vpx://example-vcenter.com/dc1/cluster1/example-esx.com
+
+Datacenters and clusters can be organized in folders, those have to be specified
+as well. The driver can handle folders :since:`since 0.9.7` .
+
+::
+
+ vpx://example-vcenter.com/folder1/dc1/folder2/example-esx.com
+
+Extra parameters
+^^^^^^^^^^^^^^^^
+
+Extra parameters can be added to a URI as part of the query string (the part
+following ``?``). A single parameter is formed by a ``name=value`` pair.
+Multiple parameters are separated by ``&``.
+
+::
+
+ ?no_verify=1&auto_answer=1&proxy=socks://example-proxy.com:23456
+
+The driver understands the extra parameters shown below.
+
++-----------------+-----------------------------+-----------------------------+
+| Name | Values | Meaning |
++=================+=============================+=============================+
+| ``transport`` | ``http`` or ``https`` | Overrides the default HTTPS |
+| | | transport. For ``esx://`` |
+| | | and ``vpx://`` the default |
+| | | HTTP port is 80, for |
+| | | ``gsx://`` it is 8222. |
++-----------------+-----------------------------+-----------------------------+
+| ``vcenter`` | Hostname of a VMware | In order to perform a |
+| | vCenter or ``*`` | migration the driver needs |
+| | | to know the VMware vCenter |
+| | | for the ESX server. If set |
+| | | to ``*``, the driver |
+| | | connects to the vCenter |
+| | | known to the ESX server. |
+| | | This parameter in useful |
+| | | when connecting to an ESX |
+| | | server only. |
++-----------------+-----------------------------+-----------------------------+
+| ``no_verify`` | ``0`` or ``1`` | If set to 1, this disables |
+| | | libcurl client checks of |
+| | | the server's SSL |
+| | | certificate. The default |
+| | | value is 0. See the |
+| | | `Certificates for |
+| | | HTTPS <#certificates>`__ |
+| | | section for details. |
++-----------------+-----------------------------+-----------------------------+
+| ``auto_answer`` | ``0`` or ``1`` | If set to 1, the driver |
+| | | answers all |
+| | | `questions <#questions>`__ |
+| | | with the default answer. If |
+| | | set to 0, questions are |
+| | | reported as errors. The |
+| | | default value is 0. |
+| | | :since:`Since 0.7.5` . |
++-----------------+-----------------------------+-----------------------------+
+| ``proxy`` | [type://]hostname[:port] | Allows to specify a proxy |
+| | | for HTTP and HTTPS |
+| | | communication. |
+| | | :since:`Since 0.8.2` . The |
+| | | optional ``type`` part may |
+| | | be one of: ``http``, |
+| | | ``socks``, ``socks4``, |
+| | | ``socks4a`` or ``socks5``. |
+| | | The default is ``http`` and |
+| | | ``socks`` is synonymous for |
+| | | ``socks5``. The optional |
+| | | ``port`` allows to override |
+| | | the default port 1080. |
++-----------------+-----------------------------+-----------------------------+
+
+Authentication
+~~~~~~~~~~~~~~
+
+In order to perform any useful operation the driver needs to log into the ESX
+server. Therefore, only ``virConnectOpenAuth`` can be used to connect to an ESX
+server, ``virConnectOpen`` and ``virConnectOpenReadOnly`` don't work. To log
+into an ESX server or vCenter the driver will request credentials using the
+callback passed to the ``virConnectOpenAuth`` function. The driver passes the
+hostname as challenge parameter to the callback. This enables the callback to
+distinguish between requests for ESX server and vCenter.
+
+**Note**: During the ongoing driver development, testing is done using an
+unrestricted ``root`` account. Problems may occur if you use a restricted
+account. Detailed testing with restricted accounts has not been done yet.
+
+Certificates for HTTPS
+~~~~~~~~~~~~~~~~~~~~~~
+
+By default the ESX driver uses HTTPS to communicate with an ESX server. Proper
+HTTPS communication requires correctly configured SSL certificates. This
+certificates are different from the ones libvirt uses for `secure communication
+over TLS <remote.html>`__ to a libvirtd one a remote server.
+
+By default the driver tries to verify the server's SSL certificate using the CA
+certificate pool installed on your client computer. With an out-of-the-box
+installed ESX server this won't work, because a newly installed ESX server uses
+auto-generated self-signed certificates. Those are signed by a CA certificate
+that is typically not known to your client computer and libvirt will report an
+error like this one:
+
+::
+
+ error: internal error curl_easy_perform() returned an error: Peer certificate cannot
be authenticated with known CA certificates (60)
+
+Where are two ways to solve this problem:
+
+- Use the ``no_verify=1`` `extra parameter <#extraparams>`__ to disable server
+ certificate verification.
+- Generate new SSL certificates signed by a CA known to your client computer
+ and replace the original ones on your ESX server. See the section *Replace a
+ Default Certificate with a CA-Signed Certificate* in the `ESX Configuration
+ Guide <https://www.vmware.com/pdf/vsphere4/r40/vsp_40_esx_server_config.pdf>`__
+
+Connection problems
+~~~~~~~~~~~~~~~~~~~
+
+There are also other causes for connection problems than the `HTTPS
+certificate <#certificates>`__ related ones.
+
+- As stated before the ESX driver doesn't need the `remote transport
+ mechanism <remote.html>`__ provided by the remote driver and libvirtd, nor
+ does the ESX driver support it. Therefore, using an URI including a transport
+ in the scheme won't work. Only `URIs as described <#uriformat>`__ are
+ supported by the ESX driver. Here's a collection of possible error messages:
+
+ ::
+
+ $ virsh -c esx+tcp://example.com/
+ error: unable to connect to libvirtd at 'example.com': Connection refused
+
+ ::
+
+ $ virsh -c esx+tls://example.com/
+ error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file
or directory
+
+ ::
+
+ $ virsh -c esx+ssh://example.com/
+ error: cannot recv data: ssh: connect to host example.com port 22: Connection
refused
+
+ ::
+
+ $ virsh -c esx+ssh://example.com/
+ error: cannot recv data: Resource temporarily unavailable
+
+- :since:`Since 0.7.0` libvirt contains the ESX driver. Earlier versions of
+ libvirt will report a misleading error about missing certificates when you
+ try to connect to an ESX server.
+
+ ::
+
+ $ virsh -c esx://example.com/
+ error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file
or directory
+
+ Don't let this error message confuse you. Setting up certificates as
+ described on the `remote transport
+ mechanism <remote.html#Remote_certificates>`__ page does not help, as this is
+ not a certificate related problem.
+
+ To fix this problem you need to update your libvirt to 0.7.0 or newer. You
+ may also see this error when you use a libvirt version that contains the ESX
+ driver but you or your distro disabled the ESX driver during compilation.
+ :since:`Since 0.8.3` the error message has been improved in this case:
+
+ ::
+
+ $ virsh -c esx://example.com/
+ error: invalid argument in libvirt was built without the 'esx' driver
+
+Questions blocking tasks
+------------------------
+
+Some methods of the VI API start tasks, for example ``PowerOnVM_Task()``. Such
+tasks may be blocked by questions if the ESX server detects an issue with the
+domain that requires user interaction. The ESX driver cannot prompt the user to
+answer a question, libvirt doesn't have an API for something like this.
+
+The VI API provides the ``AnswerVM()`` method to programmatically answer a
+questions. So the driver has two options how to handle such a situation: either
+answer the questions with the default answer or report the question as an error
+and cancel the blocked task if possible. The `auto_answer <#uriformat>`__ query
+parameter controls the answering behavior.
+
+Specialities in the domain XML config
+-------------------------------------
+
+There are several specialities in the domain XML config for ESX domains.
+
+Restrictions
+~~~~~~~~~~~~
+
+There are some restrictions for some values of the domain XML config. The driver
+will complain if this restrictions are violated.
+
+- Memory size has to be a multiple of 4096
+- Number of virtual CPU has to be 1 or a multiple of 2. :since:`Since 4.10.0`
+ any number of vCPUs is supported.
+- Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``. :since:`Since
+ 0.7.6` arbitrary `MAC addresses <#macaddresses>`__ are supported.
+
+Datastore references
+~~~~~~~~~~~~~~~~~~~~
+
+Storage is managed in datastores. VMware uses a special path format to reference
+files in a datastore. Basically, the datastore name is put into squared braces
+in front of the path.
+
+::
+
+ [datastore] directory/filename
+
+To define a new domain the driver converts the domain XML into a VMware VMX file
+and uploads it to a datastore known to the ESX server. Because multiple
+datastores may be known to an ESX server the driver needs to decide to which
+datastore the VMX file should be uploaded. The driver deduces this information
+from the path of the source of the first file-based harddisk listed in the
+domain XML.
+
+MAC addresses
+~~~~~~~~~~~~~
+
+VMware has registered two MAC address prefixes for domains: ``00:0c:29`` and
+``00:50:56``. These prefixes are split into ranges for different purposes.
+
++--------------------------------------+--------------------------------------+
+| Range | Purpose |
++======================================+======================================+
+| ``00:0c:29:00:00:00`` - | An ESX server autogenerates MAC |
+| ``00:0c:29:ff:ff:ff`` | addresses from this range if the VMX |
+| | file doesn't contain a MAC address |
+| | when trying to start a domain. |
++--------------------------------------+--------------------------------------+
+| ``00:50:56:00:00:00`` - | MAC addresses from this range can by |
+| ``00:50:56:3f:ff:ff`` | manually assigned by the user in the |
+| | VI client. |
++--------------------------------------+--------------------------------------+
+| ``00:50:56:80:00:00`` - | A VI client autogenerates MAC |
+| ``00:50:56:bf:ff:ff`` | addresses from this range for newly |
+| | defined domains. |
++--------------------------------------+--------------------------------------+
+
+The VMX files generated by the ESX driver always contain a MAC address, because
+libvirt generates a random one if an interface element in the domain XML file
+lacks a MAC address. :since:`Since 0.7.6` the ESX driver sets the prefix for
+generated MAC addresses to ``00:0c:29``. Before 0.7.6 the ``00:50:56`` prefix
+was used. Sometimes this resulted in the generation of out-of-range MAC address
+that were rejected by the ESX server.
+
+Also :since:`since 0.7.6` every MAC address outside this ranges can be used. For
+such MAC addresses the ESX server-side check is disabled in the VMX file to stop
+the ESX server from rejecting out-of-predefined-range MAC addresses.
+
+::
+
+ ethernet0.checkMACAddress = "false"
+
+:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC address
+when it's in the reserved VMware range by adding a ``type="static"``
attribute
+to the ``<mac/>`` element. Note that this attribute is useless if the provided
+MAC address is outside of the reserved VMWare ranges.
+
+Available hardware
+~~~~~~~~~~~~~~~~~~
+
+VMware ESX supports different models of SCSI controllers and network cards.
+
+SCSI controller models
+^^^^^^^^^^^^^^^^^^^^^^
+
+``auto``
+ This isn't an actual controller model. If specified the ESX driver tries to
+ detect the SCSI controller model referenced in the ``.vmdk`` file and use it.
+ Autodetection fails when a SCSI controller has multiple disks attached and
+ the SCSI controller models referenced in the ``.vmdk`` files are
+ inconsistent. :since:`Since 0.8.3`
+``buslogic``
+ BusLogic SCSI controller for older guests.
+``lsilogic``
+ LSI Logic SCSI controller for recent guests.
+``lsisas1068``
+ LSI Logic SAS 1068 controller. :since:`Since 0.8.0`
+``vmpvscsi``
+ Special VMware Paravirtual SCSI controller, requires VMware tools inside the
+ guest. See `VMware KB1010398 <https://kb.vmware.com/kb/1010398>`__ for
+ details. :since:`Since 0.8.3`
+
+Here a domain XML snippet:
+
+::
+
+ ...
+ <disk type='file' device='disk'>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='0' bus='0'
unit='0'/>
+ </disk>
+ <controller type='scsi' index='0' model='lsilogic'/>
+ ...
+
+The controller element is supported :since:`since 0.8.2` . Prior to this
+``<driver name='lsilogic'/>`` was abused to specify the SCSI controller
model.
+This attribute usage is deprecated now.
+
+::
+
+ ...
+ <disk type='file' device='disk'>
+ <driver name='lsilogic'/>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ </disk>
+ ...
+
+Network card models
+^^^^^^^^^^^^^^^^^^^
+
+``vlance``
+ AMD PCnet32 network card for older guests.
+``vmxnet``, ``vmxnet2``, ``vmxnet3``
+ Special VMware VMXnet network card, requires VMware tools inside the guest.
+ See `VMware KB1001805 <https://kb.vmware.com/kb/1001805>`__ for details.
+``e1000``
+ Intel E1000 network card for recent guests.
+
+Here a domain XML snippet:
+
+::
+
+ ...
+ <interface type='bridge'>
+ <mac address='00:50:56:25:48:c7'/>
+ <source bridge='VM Network'/>
+ <model type='e1000'/>
+ </interface>
+ ...
+
+Import and export of domain XML configs
+---------------------------------------
+
+The ESX driver currently supports a native config format known as ``vmware-vmx``
+to handle VMware VMX configs.
+
+Converting from VMware VMX config to domain XML config
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-from-native`` provides a way to convert an existing VMware
+VMX config into a domain XML config that can then be used by libvirt.
+
+::
+
+ $ cat > demo.vmx << EOF
+ #!/usr/bin/vmware
+ config.version = "8"
+ virtualHW.version = "4"
+ floppy0.present = "false"
+ nvram = "Fedora11.nvram"
+ deploymentPlatform = "windows"
+ virtualHW.productCompatibility = "hosted"
+ tools.upgrade.policy = "useGlobal"
+ powerType.powerOff = "default"
+ powerType.powerOn = "default"
+ powerType.suspend = "default"
+ powerType.reset = "default"
+ displayName = "Fedora11"
+ extendedConfigFile = "Fedora11.vmxf"
+ scsi0.present = "true"
+ scsi0.sharedBus = "none"
+ scsi0.virtualDev = "lsilogic"
+ memsize = "1024"
+ scsi0:0.present = "true"
+ scsi0:0.fileName =
"/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11.vmdk"
+ scsi0:0.deviceType = "scsi-hardDisk"
+ ide0:0.present = "true"
+ ide0:0.clientDevice = "true"
+ ide0:0.deviceType = "cdrom-raw"
+ ide0:0.startConnected = "false"
+ ethernet0.present = "true"
+ ethernet0.networkName = "VM Network"
+ ethernet0.addressType = "vpx"
+ ethernet0.generatedAddress = "00:50:56:91:48:c7"
+ chipset.onlineStandby = "false"
+ guestOSAltName = "Red Hat Enterprise Linux 5 (32-Bit)"
+ guestOS = "rhel5"
+ uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
+ snapshot.action = "keep"
+ sched.cpu.min = "0"
+ sched.cpu.units = "mhz"
+ sched.cpu.shares = "normal"
+ sched.mem.minsize = "0"
+ sched.mem.shares = "normal"
+ toolScripts.afterPowerOn = "true"
+ toolScripts.afterResume = "true"
+ toolScripts.beforeSuspend = "true"
+ toolScripts.beforePowerOff = "true"
+ scsi0:0.redo = ""
+ tools.syncTime = "false"
+ uuid.location = "56 4d b5 06 a2 bd fb eb-ae 86 f7 d8 49 27 d0 c4"
+ sched.cpu.max = "unlimited"
+ sched.swap.derivedName =
"/vmfs/volumes/498076b2-02796c1a-ef5b-000ae484a6a3/Fedora11/Fedora11-7de040d8.vswp"
+ tools.remindInstall = "TRUE"
+ EOF
+
+ $ virsh -c esx://example.com domxml-from-native vmware-vmx demo.vmx
+ Enter username for example.com [root]:
+ Enter root password for example.com:
+ <domain type='vmware'>
+ <name>Fedora11</name>
+ <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
+ <memory>1048576</memory>
+ <currentMemory>1048576</currentMemory>
+ <vcpu>1</vcpu>
+ <os>
+ <type arch='i686'>hvm</type>
+ </os>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <disk type='file' device='disk'>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='0' bus='0'
unit='0'/>
+ </disk>
+ <controller type='scsi' index='0'
model='lsilogic'/>
+ <interface type='bridge'>
+ <mac address='00:50:56:91:48:c7'/>
+ <source bridge='VM Network'/>
+ </interface>
+ </devices>
+ </domain>
+
+Converting from domain XML config to VMware VMX config
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-to-native`` provides a way to convert a domain XML config
+into a VMware VMX config.
+
+::
+
+ $ cat > demo.xml << EOF
+ <domain type='vmware'>
+ <name>Fedora11</name>
+ <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
+ <memory>1048576</memory>
+ <currentMemory>1048576</currentMemory>
+ <vcpu>1</vcpu>
+ <os>
+ <type arch='x86_64'>hvm</type>
+ </os>
+ <devices>
+ <disk type='file' device='disk'>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='0' bus='0'
unit='0'/>
+ </disk>
+ <controller type='scsi' index='0'
model='lsilogic'/>
+ <interface type='bridge'>
+ <mac address='00:50:56:25:48:c7'/>
+ <source bridge='VM Network'/>
+ </interface>
+ </devices>
+ </domain>
+ EOF
+
+ $ virsh -c esx://example.com domxml-to-native vmware-vmx demo.xml
+ Enter username for example.com [root]:
+ Enter root password for example.com:
+ config.version = "8"
+ virtualHW.version = "4"
+ guestOS = "other-64"
+ uuid.bios = "50 11 5e 16 9b dc 49 d7-f1 71 53 c4 d7 f9 17 10"
+ displayName = "Fedora11"
+ memsize = "1024"
+ numvcpus = "1"
+ scsi0.present = "true"
+ scsi0.virtualDev = "lsilogic"
+ scsi0:0.present = "true"
+ scsi0:0.deviceType = "scsi-hardDisk"
+ scsi0:0.fileName = "/vmfs/volumes/local-storage/Fedora11/Fedora11.vmdk"
+ ethernet0.present = "true"
+ ethernet0.networkName = "VM Network"
+ ethernet0.connectionType = "bridged"
+ ethernet0.addressType = "static"
+ ethernet0.address = "00:50:56:25:48:C7"
+
+Example domain XML configs
+--------------------------
+
+Fedora11 on x86_64
+~~~~~~~~~~~~~~~~~~
+
+::
+
+ <domain type='vmware'>
+ <name>Fedora11</name>
+ <uuid>50115e16-9bdc-49d7-f171-53c4d7f91710</uuid>
+ <memory>1048576</memory>
+ <currentMemory>1048576</currentMemory>
+ <vcpu>1</vcpu>
+ <os>
+ <type arch='x86_64'>hvm</type>
+ </os>
+ <devices>
+ <disk type='file' device='disk'>
+ <source file='[local-storage] Fedora11/Fedora11.vmdk'/>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='0' bus='0'
unit='0'/>
+ </disk>
+ <controller type='scsi' index='0'/>
+ <interface type='bridge'>
+ <mac address='00:50:56:25:48:c7'/>
+ <source bridge='VM Network'/>
+ </interface>
+ </devices>
+ </domain>
+
+Migration
+---------
+
+A migration cannot be initiated on an ESX server directly, a VMware vCenter is
+necessary for this. The ``vcenter`` query parameter must be set either to the
+hostname or IP address of the vCenter managing the ESX server or to ``*``.
+Setting it to ``*`` causes the driver to connect to the vCenter known to the ESX
+server. If the ESX server is not managed by a vCenter an error is reported.
+
+::
+
+ esx://example.com/?vcenter=example-vcenter.com
+
+Here's an example how to migrate the domain ``Fedora11`` from ESX server
+``example-src.com`` to ESX server ``example-dst.com`` implicitly involving
+vCenter ``example-vcenter.com`` using ``virsh``.
+
+::
+
+ $ virsh -c esx://example-src.com/?vcenter=* migrate Fedora11
esx://example-dst.com/?vcenter=*
+ Enter username for example-src.com [root]:
+ Enter root password for example-src.com:
+ Enter username for example-vcenter.com [administrator]:
+ Enter administrator password for example-vcenter.com:
+ Enter username for example-dst.com [root]:
+ Enter root password for example-dst.com:
+ Enter username for example-vcenter.com [administrator]:
+ Enter administrator password for example-vcenter.com:
+
+:since:`Since 0.8.3` you can directly connect to a vCenter. This simplifies
+migration a bit. Here's the same migration as above but using ``vpx://``
+connections and assuming both ESX server are in datacenter ``dc1`` and aren't
+part of a cluster.
+
+::
+
+ $ virsh -c vpx://example-vcenter.com/dc1/example-src.com migrate Fedora11
vpx://example-vcenter.com/dc1/example-dst.com
+ Enter username for example-vcenter.com [administrator]:
+ Enter administrator password for example-vcenter.com:
+ Enter username for example-vcenter.com [administrator]:
+ Enter administrator password for example-vcenter.com:
+
+Scheduler configuration
+-----------------------
+
+The driver exposes the ESX CPU scheduler. The parameters listed below are
+available to control the scheduler.
+
+``reservation``
+ The amount of CPU resource in MHz that is guaranteed to be available to the
+ domain. Valid values are 0 and greater.
+``limit``
+ The CPU utilization of the domain will be limited to this value in MHz, even
+ if more CPU resources are available. If the limit is set to -1, the CPU
+ utilization of the domain is unlimited. If the limit is not set to -1, it
+ must be greater than or equal to the reservation.
+``shares``
+ Shares are used to determine relative CPU allocation between domains. In
+ general, a domain with more shares gets proportionally more of the CPU
+ resource. Valid values are 0 and greater. The special values -1, -2 and -3
+ represent the predefined shares level ``low``, ``normal`` and ``high``.
+
+VMware tools
+------------
+
+Some actions require installed VMware tools. If the VMware tools are not
+installed in the guest and one of the actions below is to be performed the ESX
+server raises an error and the driver reports it.
+
+- ``virDomainGetHostname``
+- ``virDomainInterfaceAddresses`` (only for the
+ ``VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT`` source)
+- ``virDomainReboot``
+- ``virDomainShutdown``
+
+Links
+-----
+
+- `VMware vSphere Web Services SDK
+ Documentation <https://www.vmware.com/support/developer/vc-sdk/>`__
+- `The Role of Memory in VMware ESX Server
+ 3 <https://www.vmware.com/pdf/esx3_memory.pdf>`__
+- `VMware VMX config parameters <https://www.sanbarrow.com/vmx.html>`__
+- `VMware ESX 4.0 PVSCSI Storage
+ Performance <https://www.vmware.com/pdf/vsp_4_pvscsi_perf.pdf>`__
diff --git a/docs/meson.build b/docs/meson.build
index a6c3077f25..0465c22274 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvesx',
'drvhyperv',
'drvlxc',
'drvnodedev',
@@ -80,6 +79,7 @@ docs_rst_files = [
'drivers',
'drvbhyve',
'drvch',
+ 'drvesx',
'drvqemu',
'errors',
'formatbackup',
--
2.35.1
6:46 a.m.
New subject: [PATCH 04/29] docs: Convert 'drvesx' page to rST
...
++-----------------+-----------------------------+-----------------------------+
+| ``auto_answer`` | ``0`` or ``1`` | If set to 1, the driver |
+| | | answers all |
+| | | `questions <#questions>`__ |
+| | | with the default answer. If |
+| | | set to 0, questions are |
+| | | reported as errors. The |
+| | | default value is 0. |
+| | | :since:`Since 0.7.5` . |
++-----------------+-----------------------------+-----------------------------+
+| ``proxy`` | [type://]hostname[:port] | Allows to specify a proxy |
^This one failed to convert to verbatim and needs be
tweaked by hand - I tried and it looks like nothing broke
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
9:26 a.m.
New subject: [PATCH 04/29] docs: Convert 'drvesx' page to rST
On Fri, Apr 01, 2022 at 13:46:42 +0200, Erik Skultety wrote:
...
> ++-----------------+-----------------------------+-----------------------------+
> +| ``auto_answer`` | ``0`` or ``1`` | If set to 1, the driver |
> +| | | answers all |
> +| | | `questions <#questions>`__
|
> +| | | with the default answer. If |
> +| | | set to 0, questions are |
> +| | | reported as errors. The |
> +| | | default value is 0. |
> +| | | :since:`Since 0.7.5` . |
> ++-----------------+-----------------------------+-----------------------------+
> +| ``proxy`` | [type://]hostname[:port] | Allows to specify a proxy |
^This one failed to convert to verbatim and needs be
tweaked by hand - I tried and it looks like nothing broke
I think the issue was that it's too long once you add backticks to turn
it into verbatim. Anyways. I can change 'hostname' to 'host' to make it
fit if you agree.
9:31 a.m.
New subject: [PATCH 04/29] docs: Convert 'drvesx' page to rST
On Fri, Apr 01, 2022 at 04:26:49PM +0200, Peter Krempa wrote:
On Fri, Apr 01, 2022 at 13:46:42 +0200, Erik Skultety wrote:
> ...
>
> >
++-----------------+-----------------------------+-----------------------------+
> > +| ``auto_answer`` | ``0`` or ``1`` | If set to 1, the driver
|
> > +| | | answers all
|
> > +| | | `questions
<#questions>`__ |
> > +| | | with the default answer. If
|
> > +| | | set to 0, questions are
|
> > +| | | reported as errors. The
|
> > +| | | default value is 0.
|
> > +| | | :since:`Since 0.7.5` .
|
> >
++-----------------+-----------------------------+-----------------------------+
> > +| ``proxy`` | [type://]hostname[:port] | Allows to specify a proxy
|
>
> ^This one failed to convert to verbatim and needs be
> tweaked by hand - I tried and it looks like nothing broke
I think the issue was that it's too long once you add backticks to turn
it into verbatim. Anyways. I can change 'hostname' to 'host' to make it
fit if you agree.
Yes, but even without the spaces it works, but yours works too, go ahead.
Erik
7:10 a.m.
New subject: [PATCH 05/29] docs: Convert 'drvhyperv' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvhyperv.html.in | 150 -----------------------------------------
docs/drvhyperv.rst | 121 +++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 122 insertions(+), 151 deletions(-)
delete mode 100644 docs/drvhyperv.html.in
create mode 100644 docs/drvhyperv.rst
diff --git a/docs/drvhyperv.html.in b/docs/drvhyperv.html.in
deleted file mode 100644
index bce4e4128b..0000000000
--- a/docs/drvhyperv.html.in
+++ /dev/null
@@ -1,150 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Microsoft Hyper-V hypervisor driver</h1>
- <ul id="toc"></ul>
- <p>
- The libvirt Microsoft Hyper-V driver can manage Hyper-V 2012 R2 and newer.
- </p>
-
-
- <h2><a id="project">Project Links</a></h2>
- <ul>
- <li>
- The <a href="http://www.microsoft.com/hyper-v-server/">Microsoft
Hyper-V</a>
- hypervisor
- </li>
- </ul>
-
-
- <h2><a id="uri">Connections to the Microsoft Hyper-V
driver</a></h2>
- <p>
- Some example remote connection URIs for the driver are:
- </p>
-<pre>
-hyperv://example-hyperv.com (over HTTPS)
-hyperv://example-hyperv.com/?transport=http (over HTTP)
-</pre>
- <p>
- <strong>Note</strong>: In contrast to other drivers, the Hyper-V
driver
- is a client-side-only driver. It connects to the Hyper-V server using
- WS-Management over HTTP(S). Therefore, the
- <a href="remote.html">remote transport mechanism</a>
provided by the
- remote driver and libvirtd will not work, and you cannot use URIs like
- <code>hyperv+ssh://example.com</code>.
- </p>
-
-
- <h3><a id="uriformat">URI Format</a></h3>
- <p>
- URIs have this general form (<code>[...]</code> marks an optional
part).
- </p>
-<pre>
-hyperv://[username@]hostname[:port]/[?extraparameters]
-</pre>
- <p>
- The default HTTPS ports is 5986. If the port parameter is given, it
- overrides the default port.
- </p>
-
-
- <h4><a id="extraparams">Extra parameters</a></h4>
- <p>
- Extra parameters can be added to a URI as part of the query string
- (the part following <code>?</code>). A single parameter is formed by
a
- <code>name=value</code> pair. Multiple parameters are separated by
- <code>&</code>.
- </p>
-<pre>
-?transport=http
-</pre>
- <p>
- The driver understands the extra parameters shown below.
- </p>
- <table class="top_table">
- <tr>
- <th>Name</th>
- <th>Values</th>
- <th>Meaning</th>
- </tr>
- <tr>
- <td>
- <code>transport</code>
- </td>
- <td>
- <code>http</code> or <code>https</code>
- </td>
- <td>
- Overrides the default HTTPS transport. The default HTTP port
- is 5985.
- </td>
- </tr>
- </table>
-
-
- <h3><a id="auth">Authentication</a></h3>
- <p>
- In order to perform any useful operation the driver needs to log into
- the Hyper-V server. Therefore, only <code>virConnectOpenAuth</code>
can
- be used to connect to an Hyper-V server, <code>virConnectOpen</code>
and
- <code>virConnectOpenReadOnly</code> don't work.
- To log into an Hyper-V server the driver will request credentials using
- the callback passed to the <code>virConnectOpenAuth</code> function.
- The driver passes the hostname as challenge parameter to the callback.
- </p>
- <p>
- <strong>Note</strong>: Currently only <code>Basic</code>
authentication
- is supported by libvirt. This method is disabled by default on the
- Hyper-V server and can be enabled via the WinRM commandline tool.
- </p>
-<pre>
-winrm set winrm/config/service/auth @{Basic="true"}
-</pre>
- <p>
- To allow <code>Basic</code> authentication with HTTP transport WinRM
- needs to allow unencrypted communication. This can be enabled via the
- WinRM commandline tool. However, this is not the recommended
- communication mode.
- </p>
-<pre>
-winrm set winrm/config/service @{AllowUnencrypted="true"}
-</pre>
-
-
- <h2><a id="versions">Version Numbers</a></h2>
- <p>
- Since Microsoft's build numbers are almost always over 1000, this driver
- needs to pack the value differently compared to the format defined by
- <code>virConnectGetVersion</code>.
- To preserve all of the digits, the following format is used:
- </p>
- <pre>major * 100000000 + minor * 1000000 + micro</pre>
- <p>
- This results in <code>virsh version</code> producing unexpected
output.
- </p>
- <table class="top_table">
- <thead>
- <th>Windows Release</th>
- <th>Kernel Version</th>
- <th>libvirt Representation</th>
- </thead>
- <tr>
- <td>Windows Server 2012 R2</td>
- <td>6.3.9600</td>
- <td>603.9.600</td>
- </tr>
- <tr>
- <td>Windows Server 2016</td>
- <td>10.0.14393</td>
- <td>1000.14.393</td>
- </tr>
- <tr>
- <td>Windows Server 2019</td>
- <td>10.0.17763</td>
- <td>1000.17.763</td>
- </tr>
- </table>
-
-
-</body></html>
diff --git a/docs/drvhyperv.rst b/docs/drvhyperv.rst
new file mode 100644
index 0000000000..17d620f29c
--- /dev/null
+++ b/docs/drvhyperv.rst
@@ -0,0 +1,121 @@
+===================================
+Microsoft Hyper-V hypervisor driver
+===================================
+
+.. contents::
+
+The libvirt Microsoft Hyper-V driver can manage Hyper-V 2012 R2 and newer.
+
+Project Links
+-------------
+
+- The `Microsoft Hyper-V <http://www.microsoft.com/hyper-v-server/>`__
+ hypervisor
+
+Connections to the Microsoft Hyper-V driver
+-------------------------------------------
+
+Some example remote connection URIs for the driver are:
+
+::
+
+ hyperv://example-hyperv.com (over HTTPS)
+ hyperv://example-hyperv.com/?transport=http (over HTTP)
+
+**Note**: In contrast to other drivers, the Hyper-V driver is a client-side-only
+driver. It connects to the Hyper-V server using WS-Management over HTTP(S).
+Therefore, the `remote transport mechanism <remote.html>`__ provided by the
+remote driver and libvirtd will not work, and you cannot use URIs like
+``hyperv+ssh://example.com``.
+
+URI Format
+~~~~~~~~~~
+
+URIs have this general form (``[...]`` marks an optional part).
+
+::
+
+ hyperv://[username@]hostname[:port]/[?extraparameters]
+
+The default HTTPS ports is 5986. If the port parameter is given, it overrides
+the default port.
+
+Extra parameters
+^^^^^^^^^^^^^^^^
+
+Extra parameters can be added to a URI as part of the query string (the part
+following ``?``). A single parameter is formed by a ``name=value`` pair.
+Multiple parameters are separated by ``&``.
+
+::
+
+ ?transport=http
+
+The driver understands the extra parameters shown below.
+
++---------------+-----------------------+-------------------------------------+
+| Name | Values | Meaning |
++===============+=======================+=====================================+
+| ``transport`` | ``http`` or ``https`` | Overrides the default HTTPS |
+| | | transport. The default HTTP port is |
+| | | 5985. |
++---------------+-----------------------+-------------------------------------+
+
+Authentication
+~~~~~~~~~~~~~~
+
+In order to perform any useful operation the driver needs to log into the
+Hyper-V server. Therefore, only ``virConnectOpenAuth`` can be used to connect to
+an Hyper-V server, ``virConnectOpen`` and ``virConnectOpenReadOnly`` don't work.
+To log into an Hyper-V server the driver will request credentials using the
+callback passed to the ``virConnectOpenAuth`` function. The driver passes the
+hostname as challenge parameter to the callback.
+
+**Note**: Currently only ``Basic`` authentication is supported by libvirt. This
+method is disabled by default on the Hyper-V server and can be enabled via the
+WinRM commandline tool.
+
+::
+
+ winrm set winrm/config/service/auth @{Basic="true"}
+
+To allow ``Basic`` authentication with HTTP transport WinRM needs to allow
+unencrypted communication. This can be enabled via the WinRM commandline tool.
+However, this is not the recommended communication mode.
+
+::
+
+ winrm set winrm/config/service @{AllowUnencrypted="true"}
+
+Version Numbers
+---------------
+
+Since Microsoft's build numbers are almost always over 1000, this driver needs
+to pack the value differently compared to the format defined by
+``virConnectGetVersion``. To preserve all of the digits, the following format is
+used:
+
+::
+
+ major * 100000000 + minor * 1000000 + micro
+
+This results in ``virsh version`` producing unexpected output.
+
+.. list-table::
+ :header-rows: 1
+
+ * - Windows Release
+ - Kernel Version
+ - libvirt Representation
+
+ * - Windows Server 2012 R2
+ - 6.3.9600
+ - 603.9.600
+
+ * - Windows Server 2016
+ - 10.0.14393
+ - 1000.14.393
+
+ * - Windows Server 2019
+ - 10.0.17763
+ - 1000.17.763
diff --git a/docs/meson.build b/docs/meson.build
index 0465c22274..cfbde2a58d 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvhyperv',
'drvlxc',
'drvnodedev',
'drvopenvz',
@@ -80,6 +79,7 @@ docs_rst_files = [
'drvbhyve',
'drvch',
'drvesx',
+ 'drvhyperv',
'drvqemu',
'errors',
'formatbackup',
--
2.35.1
7:10 a.m.
New subject: [PATCH 06/29] docs: Convert 'drvlxc' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvlxc.html.in | 822 --------------------------------------------
docs/drvlxc.rst | 670 ++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 671 insertions(+), 823 deletions(-)
delete mode 100644 docs/drvlxc.html.in
create mode 100644 docs/drvlxc.rst
diff --git a/docs/drvlxc.html.in b/docs/drvlxc.html.in
deleted file mode 100644
index 23aae991a2..0000000000
--- a/docs/drvlxc.html.in
+++ /dev/null
@@ -1,822 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>LXC container driver</h1>
-
- <ul id="toc"></ul>
-
-<p>
-The libvirt LXC driver manages "Linux Containers". At their simplest,
containers
-can just be thought of as a collection of processes, separated from the main
-host processes via a set of resource namespaces and constrained via control
-groups resource tunables. The libvirt LXC driver has no dependency on the LXC
-userspace tools hosted on sourceforge.net. It directly utilizes the relevant
-kernel features to build the container environment. This allows for sharing
-of many libvirt technologies across both the QEMU/KVM and LXC drivers. In
-particular sVirt for mandatory access control, auditing of operations,
-integration with control groups and many other features.
-</p>
-
-<h2><a id="cgroups">Control groups
Requirements</a></h2>
-
-<p>
-In order to control the resource usage of processes inside containers, the
-libvirt LXC driver requires that certain cgroups controllers are mounted on
-the host OS. The minimum required controllers are 'cpuacct', 'memory'
and
-'devices', while recommended extra controllers are 'cpu',
'freezer' and
-'blkio'. Libvirt will not mount the cgroups filesystem itself, leaving
-this up to the init system to take care of. Systemd will do the right thing
-in this respect, while for other init systems the <code>cgconfig</code>
-init service will be required. For further information, consult the general
-libvirt <a href="cgroups.html">cgroups documentation</a>.
-</p>
-
-<h2><a id="namespaces">Namespace requirements</a></h2>
-
-<p>
-In order to separate processes inside a container from those in the
-primary "host" OS environment, the libvirt LXC driver requires that
-certain kernel namespaces are compiled in. Libvirt currently requires
-the 'mount', 'ipc', 'pid', and 'uts' namespaces to be
available. If
-separate network interfaces are desired, then the 'net' namespace is
-required. If the guest configuration declares a
-<a href="formatdomain.html#elementsOSContainer">UID or GID
mapping</a>,
-the 'user' namespace will be enabled to apply these. <strong>A suitably
-configured UID/GID mapping is a pre-requisite to making containers
-secure, in the absence of sVirt confinement.</strong>
-</p>
-
-<h2><a id="init">Default container setup</a></h2>
-
-<h3><a id="cliargs">Command line arguments</a></h3>
-
-<p>
-When the container "init" process is started, it will typically
-not be given any command line arguments (eg the equivalent of
-the bootloader args visible in <code>/proc/cmdline</code>). If
-any arguments are desired, then must be explicitly set in the
-container XML configuration via one or more <code>initarg</code>
-elements. For example, to run <code>systemd --unit emergency.service</code>
-would use the following XML
-</p>
-
-<pre>
-<os>
- <type arch='x86_64'>exe</type>
- <init>/bin/systemd</init>
- <initarg>--unit</initarg>
- <initarg>emergency.service</initarg>
-</os>
-</pre>
-
-<h3><a id="envvars">Environment variables</a></h3>
-
-<p>
-When the container "init" process is started, it will be given several useful
-environment variables. The following standard environment variables are mandated
-by <a
href="https://www.freedesktop.org/wiki/Software/systemd/ContainerInt...
container interface</a>
-to be provided by all container technologies on Linux.
-</p>
-
-<dl>
-<dt><code>container</code></dt>
-<dd>The fixed string <code>libvirt-lxc</code> to identify libvirt as
the creator</dd>
-<dt><code>container_uuid</code></dt>
-<dd>The UUID assigned to the container by libvirt</dd>
-<dt><code>PATH</code></dt>
-<dd>The fixed string <code>/bin:/usr/bin</code></dd>
-<dt><code>TERM</code></dt>
-<dd>The fixed string <code>linux</code></dd>
-<dt><code>HOME</code></dt>
-<dd>The fixed string <code>/</code></dd>
-</dl>
-
-<p>
-In addition to the standard variables, the following libvirt specific
-environment variables are also provided
-</p>
-
-<dl>
-<dt><code>LIBVIRT_LXC_NAME</code></dt>
-<dd>The name assigned to the container by libvirt</dd>
-<dt><code>LIBVIRT_LXC_UUID</code></dt>
-<dd>The UUID assigned to the container by libvirt</dd>
-<dt><code>LIBVIRT_LXC_CMDLINE</code></dt>
-<dd>The unparsed command line arguments specified in the container configuration.
-Use of this is discouraged, in favour of passing arguments directly to the
-container init process via the <code>initarg</code> config
element.</dd>
-</dl>
-
-<h3><a id="fsmounts">Filesystem mounts</a></h3>
-
-<p>
-In the absence of any explicit configuration, the container will
-inherit the host OS filesystem mounts. A number of mount points will
-be made read only, or re-mounted with new instances to provide
-container specific data. The following special mounts are setup
-by libvirt
-</p>
-
-<ul>
-<li><code>/dev</code> a new "tmpfs" pre-populated with
authorized device nodes</li>
-<li><code>/dev/pts</code> a new private "devpts" instance for
console devices</li>
-<li><code>/sys</code> the host "sysfs" instance remounted
read-only</li>
-<li><code>/proc</code> a new instance of the "proc"
filesystem</li>
-<li><code>/proc/sys</code> the host "/proc/sys" bind-mounted
read-only</li>
-<li><code>/sys/fs/selinux</code> the host "selinux" instance
remounted read-only</li>
-<li><code>/sys/fs/cgroup/NNNN</code> the host cgroups controllers
bind-mounted to
-only expose the sub-tree associated with the container</li>
-<li><code>/proc/meminfo</code> a FUSE backed file reflecting memory
limits of the container</li>
-</ul>
-
-
-<h3><a id="devnodes">Device nodes</a></h3>
-
-<p>
-The container init process will be started with <code>CAP_MKNOD</code>
-capability removed and blocked from re-acquiring it. As such it will
-not be able to create any device nodes in <code>/dev</code> or anywhere
-else in its filesystems. Libvirt itself will take care of pre-populating
-the <code>/dev</code> filesystem with any devices that the container
-is authorized to use. The current devices that will be made available
-to all containers are
-</p>
-
-<ul>
-<li><code>/dev/zero</code></li>
-<li><code>/dev/null</code></li>
-<li><code>/dev/full</code></li>
-<li><code>/dev/random</code></li>
-<li><code>/dev/urandom</code></li>
-<li><code>/dev/stdin</code> symlinked to
<code>/proc/self/fd/0</code></li>
-<li><code>/dev/stdout</code> symlinked to
<code>/proc/self/fd/1</code></li>
-<li><code>/dev/stderr</code> symlinked to
<code>/proc/self/fd/2</code></li>
-<li><code>/dev/fd</code> symlinked to
<code>/proc/self/fd</code></li>
-<li><code>/dev/ptmx</code> symlinked to
<code>/dev/pts/ptmx</code></li>
-<li><code>/dev/console</code> symlinked to
<code>/dev/pts/0</code></li>
-</ul>
-
-<p>
-In addition, for every console defined in the guest configuration,
-a symlink will be created from <code>/dev/ttyN</code> symlinked to
-the corresponding <code>/dev/pts/M</code> pseudo TTY device. The
-first console will be <code>/dev/tty1</code>, with further consoles
-numbered incrementally from there.
-</p>
-
-<p>
-Since /dev/ttyN and /dev/console are linked to the pts devices. The
-tty device of login program is pts device. The pam module securetty
-may prevent root user from logging in container. If you want root
-user to log in container successfully, add the pts device to the file
-/etc/securetty of container.
-</p>
-
-<p>
-Further block or character devices will be made available to containers
-depending on their configuration.
-</p>
-
-<h2><a id="security">Security considerations</a></h2>
-
-<p>
-The libvirt LXC driver is fairly flexible in how it can be configured,
-and as such does not enforce a requirement for strict security
-separation between a container and the host. This allows it to be used
-in scenarios where only resource control capabilities are important,
-and resource sharing is desired. Applications wishing to ensure secure
-isolation between a container and the host must ensure that they are
-writing a suitable configuration.
-</p>
-
-<h3><a id="securenetworking">Network
isolation</a></h3>
-
-<p>
-If the guest configuration does not list any network interfaces,
-the <code>network</code> namespace will not be activated, and thus
-the container will see all the host's network interfaces. This will
-allow apps in the container to bind to/connect from TCP/UDP addresses
-and ports from the host OS. It also allows applications to access
-UNIX domain sockets associated with the host OS, which are in the
-abstract namespace. If access to UNIX domains sockets in the abstract
-namespace is not wanted, then applications should set the
-<code><privnet/></code> flag in the
-<code><features>....</features></code> element.
-</p>
-
-<h3><a id="securefs">Filesystem isolation</a></h3>
-
-<p>
-If the guest configuration does not list any filesystems, then
-the container will be set up with a root filesystem that matches
-the host's root filesystem. As noted earlier, only a few locations
-such as <code>/dev</code>, <code>/proc</code> and
<code>/sys</code>
-will be altered. This means that, in the absence of restrictions
-from sVirt, a process running as user/group N:M inside the container
-will be able to access almost exactly the same files as a process
-running as user/group N:M in the host.
-</p>
-
-<p>
-There are multiple options for restricting this. It is possible to
-simply map the existing root filesystem through to the container in
-read-only mode. Alternatively a completely separate root filesystem
-can be configured for the guest. In both cases, further sub-mounts
-can be applied to customize the content that is made visible. Note
-that in the absence of sVirt controls, it is still possible for the
-root user in a container to unmount any sub-mounts applied. The user
-namespace feature can also be used to restrict access to files based
-on the UID/GID mappings.
-</p>
-
-<p>
-Sharing the host filesystem tree, also allows applications to access
-UNIX domains sockets associated with the host OS, which are in the
-filesystem namespaces. It should be noted that a number of init
-systems including at least <code>systemd</code> and
<code>upstart</code>
-have UNIX domain socket which are used to control their operation.
-Thus, if the directory/filesystem holding their UNIX domain socket is
-exposed to the container, it will be possible for a user in the container
-to invoke operations on the init service in the same way it could if
-outside the container. This also applies to other applications in the
-host which use UNIX domain sockets in the filesystem, such as DBus,
-Libvirtd, and many more. If this is not desired, then applications
-should either specify the UID/GID mapping in the configuration to
-enable user namespaces and thus block access to the UNIX domain socket
-based on permissions, or should ensure the relevant directories have
-a bind mount to hide them. This is particularly important for the
-<code>/run</code> or <code>/var/run</code> directories.
-</p>
-
-
-<h3><a id="secureusers">User and group
isolation</a></h3>
-
-<p>
-If the guest configuration does not list any ID mapping, then the
-user and group IDs used inside the container will match those used
-outside the container. In addition, the capabilities associated with
-a process in the container will infer the same privileges they would
-for a process in the host. This has obvious implications for security,
-since a root user inside the container will be able to access any
-file owned by root that is visible to the container, and perform more
-or less any privileged kernel operation. In the absence of additional
-protection from sVirt, this means that the root user inside a container
-is effectively as powerful as the root user in the host. There is no
-security isolation of the root user.
-</p>
-
-<p>
-The ID mapping facility was introduced to allow for stricter control
-over the privileges of users inside the container. It allows apps to
-define rules such as "user ID 0 in the container maps to user ID 1000
-in the host". In addition the privileges associated with capabilities
-are somewhat reduced so that they cannot be used to escape from the
-container environment. A full description of user namespaces is outside
-the scope of this document, however LWN has
-<a href="https://lwn.net/Articles/532593/">a good write-up on the
topic</a>.
-From the libvirt point of view, the key thing to remember is that defining
-an ID mapping for users and groups in the container XML configuration
-causes libvirt to activate the user namespace feature.
-</p>
-
-
-<h2><a id="configFiles">Location of configuration
files</a></h2>
-
-<p>
-The LXC driver comes with sane default values. However, during its
-initialization it reads a configuration file which offers system
-administrator to override some of that default. The file is located
-under <code>/etc/libvirt/lxc.conf</code>
-</p>
-
-
-<h2><a id="activation">Systemd Socket Activation
Integration</a></h2>
-
-<p>
-The libvirt LXC driver provides the ability to pass across pre-opened file
-descriptors when starting LXC guests. This allows for libvirt LXC to support
-systemd's <a
href="http://0pointer.de/blog/projects/socket-activated-containers.html">socket
-activation capability</a>, where an incoming client connection
-in the host OS will trigger the startup of a container, which runs another
-copy of systemd which gets passed the server socket, and then activates the
-actual service handler in the container.
-</p>
-
-<p>
-Let us assume that you already have a LXC guest created, running
-a systemd instance as PID 1 inside the container, which has an
-SSHD service configured. The goal is to automatically activate
-the container when the first SSH connection is made. The first
-step is to create a couple of unit files for the host OS systemd
-instance. The <code>/etc/systemd/system/mycontainer.service</code>
-unit file specifies how systemd will start the libvirt LXC container
-</p>
-
-<pre>
-[Unit]
-Description=My little container
-
-[Service]
-ExecStart=/usr/bin/virsh -c lxc:///system start --pass-fds 3 mycontainer
-ExecStop=/usr/bin/virsh -c lxc:///system destroy mycontainer
-Type=oneshot
-RemainAfterExit=yes
-KillMode=none
-</pre>
-
-<p>
-The <code>--pass-fds 3</code> argument specifies that the file
-descriptor number 3 that <code>virsh</code> inherits from systemd,
-is to be passed into the container. Since <code>virsh</code> will
-exit immediately after starting the container, the
<code>RemainAfterExit</code>
-and <code>KillMode</code> settings must be altered from their defaults.
-</p>
-
-<p>
-Next, the <code>/etc/systemd/system/mycontainer.socket</code> unit
-file is created to get the host systemd to listen on port 23 for
-TCP connections. When this unit file is activated by the first
-incoming connection, it will cause the <code>mycontainer.service</code>
-unit to be activated with the FD corresponding to the listening TCP
-socket passed in as FD 3.
-</p>
-
-<pre>
-[Unit]
-Description=The SSH socket of my little container
-
-[Socket]
-ListenStream=23
-</pre>
-
-<p>
-Port 23 was picked here so that the container doesn't conflict
-with the host's SSH which is on the normal port 22. That's it
-in terms of host side configuration.
-</p>
-
-<p>
-Inside the container, the <code>/etc/systemd/system/sshd.socket</code>
-unit file must be created
-</p>
-
-<pre>
-[Unit]
-Description=SSH Socket for Per-Connection Servers
-
-[Socket]
-ListenStream=23
-Accept=yes
-</pre>
-
-<p>
-The <code>ListenStream</code> value listed in this unit file, must
-match the value used in the host file. When systemd in the container
-receives the pre-opened FD from libvirt during container startup, it
-looks at the <code>ListenStream</code> values to figure out which
-FD to give to which service. The actual service to start is defined
-by a correspondingly named <code>/etc/systemd/system/sshd@.service</code>
-</p>
-
-<pre>
-[Unit]
-Description=SSH Per-Connection Server for %I
-
-[Service]
-ExecStart=-/usr/sbin/sshd -i
-StandardInput=socket
-</pre>
-
-<p>
-Finally, make sure this SSH service is set to start on boot of the container,
-by running the following command inside the container:
-</p>
-
-<pre>
-# mkdir -p /etc/systemd/system/sockets.target.wants/
-# ln -s /etc/systemd/system/sshd.socket /etc/systemd/system/sockets.target.wants/
-</pre>
-
-<p>
-This example shows how to activate the container based on an incoming
-SSH connection. If the container was also configured to have an httpd
-service, it may be desirable to activate it upon either an httpd or a
-sshd connection attempt. In this case, the <code>mycontainer.socket</code>
-file in the host would simply list multiple socket ports. Inside the
-container a separate <code>xxxxx.socket</code> file would need to be
-created for each service, with a corresponding <code>ListenStream</code>
-value set.
-</p>
-
-<!--
-<h2>Container configuration</h2>
-
-<h3>Init process</h3>
-
-<h3>Console devices</h3>
-
-<h3>Filesystem devices</h3>
-
-<h3>Disk devices</h3>
-
-<h3>Block devices</h3>
-
-<h3>USB devices</h3>
-
-<h3>Character devices</h3>
-
-<h3>Network devices</h3>
--->
-
-<h2>Container security</h2>
-
-<h3>sVirt SELinux</h3>
-
-<p>
-In the absence of the "user" namespace being used, containers cannot
-be considered secure against exploits of the host OS. The sVirt SELinux
-driver provides a way to secure containers even when the "user" namespace
-is not used. The cost is that writing a policy to allow execution of
-arbitrary OS is not practical. The SELinux sVirt policy is typically
-tailored to work with a simpler application confinement use case,
-as provided by the "libvirt-sandbox" project.
-</p>
-
-<h3>Auditing</h3>
-
-<p>
-The LXC driver is integrated with libvirt's auditing subsystem, which
-causes audit messages to be logged whenever there is an operation
-performed against a container which has impact on host resources.
-So for example, start/stop, device hotplug will all log audit messages
-providing details about what action occurred and any resources
-associated with it. There are the following 3 types of audit messages
-</p>
-
-<ul>
-<li><code>VIRT_MACHINE_ID</code> - details of the SELinux process and
-image security labels assigned to the container.</li>
-<li><code>VIRT_CONTROL</code> - details of an action / operation
-performed against a container. There are the following types of
-operation
- <ul>
- <li><code>op=start</code> - a container has been started. Provides
- the machine name, uuid and PID of the <code>libvirt_lxc</code>
- controller process</li>
- <li><code>op=init</code> - the init PID of the container has been
- started. Provides the machine name, uuid and PID of the
- <code>libvirt_lxc</code> controller process and PID of the
- init process (in the host PID namespace)</li>
- <li><code>op=stop</code> - a container has been stopped. Provides
- the machine name, uuid</li>
- </ul>
-</li>
-<li><code>VIRT_RESOURCE</code> - details of a host resource
-associated with a container action.</li>
-</ul>
-
-<h3>Device access</h3>
-
-<p>
-All containers are launched with the CAP_MKNOD capability cleared
-and removed from the bounding set. Libvirt will ensure that the
-/dev filesystem is pre-populated with all devices that a container
-is allowed to use. In addition, the cgroup "device" controller is
-configured to block read/write/mknod from all devices except those
-that a container is authorized to use.
-</p>
-
-<h2><a id="exconfig">Example configurations</a></h2>
-
-<h3>Example config version 1</h3>
-<p></p>
-<pre>
-<domain type='lxc'>
- <name>vm1</name>
- <memory>500000</memory>
- <os>
- <type>exe</type>
- <init>/bin/sh</init>
- </os>
- <vcpu>1</vcpu>
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>destroy</on_crash>
- <devices>
- <emulator>/usr/libexec/libvirt_lxc</emulator>
- <interface type='network'>
- <source network='default'/>
- </interface>
- <console type='pty' />
- </devices>
-</domain>
-</pre>
-
-<p>
-In the <emulator> element, be sure you specify the correct path
-to libvirt_lxc, if it does not live in /usr/libexec on your system.
-</p>
-
-<p>
-The next example assumes there is a private root filesystem
-(perhaps hand-crafted using busybox, or installed from media,
-debootstrap, whatever) under /opt/vm-1-root:
-</p>
-<p></p>
-<pre>
-<domain type='lxc'>
- <name>vm1</name>
- <memory>32768</memory>
- <os>
- <type>exe</type>
- <init>/init</init>
- </os>
- <vcpu>1</vcpu>
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>destroy</on_crash>
- <devices>
- <emulator>/usr/libexec/libvirt_lxc</emulator>
- <filesystem type='mount'>
- <source dir='/opt/vm-1-root'/>
- <target dir='/'/>
- </filesystem>
- <interface type='network'>
- <source network='default'/>
- </interface>
- <console type='pty' />
- </devices>
-</domain>
-</pre>
-
-<h2><a id="capabilities">Altering the available
capabilities</a></h2>
-
-<p>
-By default the libvirt LXC driver drops some capabilities among which CAP_MKNOD.
-However <span class="since">since 1.2.6</span> libvirt can be told
to keep or
-drop some capabilities using a domain configuration like the following:
-</p>
-<pre>
-...
-<features>
- <capabilities policy='default'>
- <mknod state='on'/>
- <sys_chroot state='off'/>
- </capabilities>
-</features>
-...
-</pre>
-<p>
-The capabilities children elements are named after the capabilities as defined in
-<code>man 7 capabilities</code>. An <code>off</code> state tells
libvirt to drop the
-capability, while an <code>on</code> state will force to keep the capability
even though
-this one is dropped by default.
-</p>
-<p>
-The <code>policy</code> attribute can be one of
<code>default</code>, <code>allow</code>
-or <code>deny</code>. It defines the default rules for capabilities: either
keep the
-default behavior that is dropping a few selected capabilities, or keep all capabilities
-or drop all capabilities. The interest of <code>allow</code> and
<code>deny</code> is that
-they guarantee that all capabilities will be kept (or removed) even if new ones are
added
-later.
-</p>
-<p>
-The following example, drops all capabilities but CAP_MKNOD:
-</p>
-<pre>
-...
-<features>
- <capabilities policy='deny'>
- <mknod state='on'/>
- </capabilities>
-</features>
-...
-</pre>
-<p>
-Note that allowing capabilities that are normally dropped by default can seriously
-affect the security of the container and the host.
-</p>
-
-<h2><a id="share">Inherit namespaces</a></h2>
-
-<p>
-Libvirt allows you to inherit the namespace from container/process just like lxc tools
-or docker provides to share the network namespace. The following can be used to share
-required namespaces. If we want to share only one then the other namespaces can be
ignored.
-The netns option is specific to sharenet. It can be used in cases we want to use existing
network namespace
-rather than creating new network namespace for the container. In this case privnet option
will be
-ignored.
-</p>
-<pre>
-<domain type='lxc'
xmlns:lxc='http://libvirt.org/schemas/domain/lxc/1.0'>
-...
-<lxc:namespace>
- <lxc:sharenet type='netns' value='red'/>
- <lxc:shareuts type='name' value='container1'/>
- <lxc:shareipc type='pid' value='12345'/>
-</lxc:namespace>
-</domain>
-</pre>
-
-<p>
-The use of namespace passthrough requires libvirt >= 1.2.19
-</p>
-
-<h2><a id="usage">Container usage /
management</a></h2>
-
-<p>
-As with any libvirt virtualization driver, LXC containers can be
-managed via a wide variety of libvirt based tools. At the lowest
-level the <code>virsh</code> command can be used to perform many
-tasks, by passing the <code>-c lxc:///system</code> argument. As an
-alternative to repeating the URI with every command, the
<code>LIBVIRT_DEFAULT_URI</code>
-environment variable can be set to <code>lxc:///system</code>. The
-examples that follow outline some common operations with virsh
-and LXC. For further details about usage of virsh consult its
-manual page.
-</p>
-
-<h3><a id="usageSave">Defining (saving) container
configuration</a></h3>
-
-<p>
-The <code>virsh define</code> command takes an XML configuration
-document and loads it into libvirt, saving the configuration on disk
-</p>
-
-<pre>
-# virsh -c lxc:///system define myguest.xml
-</pre>
-
-<h3><a id="usageView">Viewing container
configuration</a></h3>
-
-<p>
-The <code>virsh dumpxml</code> command can be used to view the
-current XML configuration of a container. By default the XML
-output reflects the current state of the container. If the
-container is running, it is possible to explicitly request the
-persistent configuration, instead of the current live configuration
-using the <code>--inactive</code> flag
-</p>
-
-<pre>
-# virsh -c lxc:///system dumpxml myguest
-</pre>
-
-<h3><a id="usageStart">Starting containers</a></h3>
-
-<p>
-The <code>virsh start</code> command can be used to start a
-container from a previously defined persistent configuration
-</p>
-
-<pre>
-# virsh -c lxc:///system start myguest
-</pre>
-
-<p>
-It is also possible to start so called "transient" containers,
-which do not require a persistent configuration to be saved
-by libvirt, using the <code>virsh create</code> command.
-</p>
-
-<pre>
-# virsh -c lxc:///system create myguest.xml
-</pre>
-
-
-<h3><a id="usageStop">Stopping containers</a></h3>
-
-<p>
-The <code>virsh shutdown</code> command can be used
-to request a graceful shutdown of the container. By default
-this command will first attempt to send a message to the
-init process via the <code>/dev/initctl</code> device node.
-If no such device node exists, then it will send SIGTERM
-to PID 1 inside the container.
-</p>
-
-<pre>
-# virsh -c lxc:///system shutdown myguest
-</pre>
-
-<p>
-If the container does not respond to the graceful shutdown
-request, it can be forcibly stopped using the <code>virsh destroy</code>
-</p>
-
-<pre>
-# virsh -c lxc:///system destroy myguest
-</pre>
-
-
-<h3><a id="usageReboot">Rebooting a container</a></h3>
-
-<p>
-The <code>virsh reboot</code> command can be used
-to request a graceful shutdown of the container. By default
-this command will first attempt to send a message to the
-init process via the <code>/dev/initctl</code> device node.
-If no such device node exists, then it will send SIGHUP
-to PID 1 inside the container.
-</p>
-
-<pre>
-# virsh -c lxc:///system reboot myguest
-</pre>
-
-<h3><a id="usageDelete">Undefining (deleting) a container
configuration</a></h3>
-
-<p>
-The <code>virsh undefine</code> command can be used to delete the
-persistent configuration of a container. If the guest is currently
-running, this will turn it into a "transient" guest.
-</p>
-
-<pre>
-# virsh -c lxc:///system undefine myguest
-</pre>
-
-<h3><a id="usageConnect">Connecting to a container
console</a></h3>
-
-<p>
-The <code>virsh console</code> command can be used to connect
-to the text console associated with a container.
-</p>
-
-<pre>
-# virsh -c lxc:///system console myguest
-</pre>
-
-<p>
-If the container has been configured with multiple console devices,
-then the <code>--devname</code> argument can be used to choose the
-console to connect to.
-In LXC, multiple consoles will be named
-as 'console0', 'console1', 'console2', etc.
-</p>
-
-<pre>
-# virsh -c lxc:///system console myguest --devname console1
-</pre>
-
-<h3><a id="usageEnter">Running commands in a
container</a></h3>
-
-<p>
-The <code>virsh lxc-enter-namespace</code> command can be used
-to enter the namespaces and security context of a container
-and then execute an arbitrary command.
-</p>
-
-<pre>
-# virsh -c lxc:///system lxc-enter-namespace myguest -- /bin/ls -al /dev
-</pre>
-
-<h3><a id="usageTop">Monitoring container
utilization</a></h3>
-
-<p>
-The <code>virt-top</code> command can be used to monitor the
-activity and resource utilization of all containers on a
-host
-</p>
-
-<pre>
-# virt-top -c lxc:///system
-</pre>
-
-<h3><a id="usageConvert">Converting LXC container
configuration</a></h3>
-
-<p>
-The <code>virsh domxml-from-native</code> command can be used to convert
-most of the LXC container configuration into a domain XML fragment
-</p>
-
-<pre>
-# virsh -c lxc:///system domxml-from-native lxc-tools /var/lib/lxc/myguest/config
-</pre>
-
-<p>
-This conversion has some limitations due to the fact that the
-domxml-from-native command output has to be independent of the host. Here
-are a few things to take care of before converting:
-</p>
-
-<ul>
-<li>
-Replace the fstab file referenced by <tt>lxc.mount</tt> by the corresponding
-lxc.mount.entry lines.
-</li>
-<li>
-Replace all relative sizes of tmpfs mount entries to absolute sizes. Also
-make sure that tmpfs entries all have a size option (default is 50%).
-</li>
-<li>
-Define <tt>lxc.cgroup.memory.limit_in_bytes</tt> to properly limit the
memory
-available to the container. The conversion will use 64MiB as the default.
-</li>
-</ul>
-
- </body>
-</html>
diff --git a/docs/drvlxc.rst b/docs/drvlxc.rst
new file mode 100644
index 0000000000..b88323b165
--- /dev/null
+++ b/docs/drvlxc.rst
@@ -0,0 +1,670 @@
+.. role:: since
+
+====================
+LXC container driver
+====================
+
+.. contents::
+
+The libvirt LXC driver manages "Linux Containers". At their simplest,
containers
+can just be thought of as a collection of processes, separated from the main
+host processes via a set of resource namespaces and constrained via control
+groups resource tunables. The libvirt LXC driver has no dependency on the LXC
+userspace tools hosted on sourceforge.net. It directly utilizes the relevant
+kernel features to build the container environment. This allows for sharing of
+many libvirt technologies across both the QEMU/KVM and LXC drivers. In
+particular sVirt for mandatory access control, auditing of operations,
+integration with control groups and many other features.
+
+Control groups Requirements
+---------------------------
+
+In order to control the resource usage of processes inside containers, the
+libvirt LXC driver requires that certain cgroups controllers are mounted on the
+host OS. The minimum required controllers are 'cpuacct', 'memory' and
'devices',
+while recommended extra controllers are 'cpu', 'freezer' and
'blkio'. Libvirt
+will not mount the cgroups filesystem itself, leaving this up to the init system
+to take care of. Systemd will do the right thing in this respect, while for
+other init systems the ``cgconfig`` init service will be required. For further
+information, consult the general libvirt `cgroups
+documentation <cgroups.html>`__.
+
+Namespace requirements
+----------------------
+
+In order to separate processes inside a container from those in the primary
+"host" OS environment, the libvirt LXC driver requires that certain kernel
+namespaces are compiled in. Libvirt currently requires the 'mount',
'ipc',
+'pid', and 'uts' namespaces to be available. If separate network
interfaces are
+desired, then the 'net' namespace is required. If the guest configuration
+declares a `UID or GID mapping <formatdomain.html#elementsOSContainer>`__, the
+'user' namespace will be enabled to apply these. **A suitably configured UID/GID
+mapping is a pre-requisite to making containers secure, in the absence of sVirt
+confinement.**
+
+Default container setup
+-----------------------
+
+Command line arguments
+~~~~~~~~~~~~~~~~~~~~~~
+
+When the container "init" process is started, it will typically not be given
any
+command line arguments (eg the equivalent of the bootloader args visible in
+``/proc/cmdline``). If any arguments are desired, then must be explicitly set in
+the container XML configuration via one or more ``initarg`` elements. For
+example, to run ``systemd --unit emergency.service`` would use the following XML
+
+::
+
+ <os>
+ <type arch='x86_64'>exe</type>
+ <init>/bin/systemd</init>
+ <initarg>--unit</initarg>
+ <initarg>emergency.service</initarg>
+ </os>
+
+Environment variables
+~~~~~~~~~~~~~~~~~~~~~
+
+When the container "init" process is started, it will be given several useful
+environment variables. The following standard environment variables are mandated
+by `systemd container
+interface
<https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface>`__
+to be provided by all container technologies on Linux.
+
+``container``
+ The fixed string ``libvirt-lxc`` to identify libvirt as the creator
+``container_uuid``
+ The UUID assigned to the container by libvirt
+``PATH``
+ The fixed string ``/bin:/usr/bin``
+``TERM``
+ The fixed string ``linux``
+``HOME``
+ The fixed string ``/``
+
+In addition to the standard variables, the following libvirt specific
+environment variables are also provided
+
+``LIBVIRT_LXC_NAME``
+ The name assigned to the container by libvirt
+``LIBVIRT_LXC_UUID``
+ The UUID assigned to the container by libvirt
+``LIBVIRT_LXC_CMDLINE``
+ The unparsed command line arguments specified in the container configuration.
+ Use of this is discouraged, in favour of passing arguments directly to the
+ container init process via the ``initarg`` config element.
+
+Filesystem mounts
+~~~~~~~~~~~~~~~~~
+
+In the absence of any explicit configuration, the container will inherit the
+host OS filesystem mounts. A number of mount points will be made read only, or
+re-mounted with new instances to provide container specific data. The following
+special mounts are setup by libvirt
+
+- ``/dev`` a new "tmpfs" pre-populated with authorized device nodes
+- ``/dev/pts`` a new private "devpts" instance for console devices
+- ``/sys`` the host "sysfs" instance remounted read-only
+- ``/proc`` a new instance of the "proc" filesystem
+- ``/proc/sys`` the host "/proc/sys" bind-mounted read-only
+- ``/sys/fs/selinux`` the host "selinux" instance remounted read-only
+- ``/sys/fs/cgroup/NNNN`` the host cgroups controllers bind-mounted to only
+ expose the sub-tree associated with the container
+- ``/proc/meminfo`` a FUSE backed file reflecting memory limits of the
+ container
+
+Device nodes
+~~~~~~~~~~~~
+
+The container init process will be started with ``CAP_MKNOD`` capability removed
+and blocked from re-acquiring it. As such it will not be able to create any
+device nodes in ``/dev`` or anywhere else in its filesystems. Libvirt itself
+will take care of pre-populating the ``/dev`` filesystem with any devices that
+the container is authorized to use. The current devices that will be made
+available to all containers are
+
+- ``/dev/zero``
+- ``/dev/null``
+- ``/dev/full``
+- ``/dev/random``
+- ``/dev/urandom``
+- ``/dev/stdin`` symlinked to ``/proc/self/fd/0``
+- ``/dev/stdout`` symlinked to ``/proc/self/fd/1``
+- ``/dev/stderr`` symlinked to ``/proc/self/fd/2``
+- ``/dev/fd`` symlinked to ``/proc/self/fd``
+- ``/dev/ptmx`` symlinked to ``/dev/pts/ptmx``
+- ``/dev/console`` symlinked to ``/dev/pts/0``
+
+In addition, for every console defined in the guest configuration, a symlink
+will be created from ``/dev/ttyN`` symlinked to the corresponding ``/dev/pts/M``
+pseudo TTY device. The first console will be ``/dev/tty1``, with further
+consoles numbered incrementally from there.
+
+Since /dev/ttyN and /dev/console are linked to the pts devices. The tty device
+of login program is pts device. The pam module securetty may prevent root user
+from logging in container. If you want root user to log in container
+successfully, add the pts device to the file /etc/securetty of container.
+
+Further block or character devices will be made available to containers
+depending on their configuration.
+
+Security considerations
+-----------------------
+
+The libvirt LXC driver is fairly flexible in how it can be configured, and as
+such does not enforce a requirement for strict security separation between a
+container and the host. This allows it to be used in scenarios where only
+resource control capabilities are important, and resource sharing is desired.
+Applications wishing to ensure secure isolation between a container and the host
+must ensure that they are writing a suitable configuration.
+
+Network isolation
+~~~~~~~~~~~~~~~~~
+
+If the guest configuration does not list any network interfaces, the ``network``
+namespace will not be activated, and thus the container will see all the host's
+network interfaces. This will allow apps in the container to bind to/connect
+from TCP/UDP addresses and ports from the host OS. It also allows applications
+to access UNIX domain sockets associated with the host OS, which are in the
+abstract namespace. If access to UNIX domains sockets in the abstract namespace
+is not wanted, then applications should set the ``<privnet/>`` flag in the
+``<features>....</features>`` element.
+
+Filesystem isolation
+~~~~~~~~~~~~~~~~~~~~
+
+If the guest configuration does not list any filesystems, then the container
+will be set up with a root filesystem that matches the host's root filesystem.
+As noted earlier, only a few locations such as ``/dev``, ``/proc`` and ``/sys``
+will be altered. This means that, in the absence of restrictions from sVirt, a
+process running as user/group N:M inside the container will be able to access
+almost exactly the same files as a process running as user/group N:M in the
+host.
+
+There are multiple options for restricting this. It is possible to simply map
+the existing root filesystem through to the container in read-only mode.
+Alternatively a completely separate root filesystem can be configured for the
+guest. In both cases, further sub-mounts can be applied to customize the content
+that is made visible. Note that in the absence of sVirt controls, it is still
+possible for the root user in a container to unmount any sub-mounts applied. The
+user namespace feature can also be used to restrict access to files based on the
+UID/GID mappings.
+
+Sharing the host filesystem tree, also allows applications to access UNIX
+domains sockets associated with the host OS, which are in the filesystem
+namespaces. It should be noted that a number of init systems including at least
+``systemd`` and ``upstart`` have UNIX domain socket which are used to control
+their operation. Thus, if the directory/filesystem holding their UNIX domain
+socket is exposed to the container, it will be possible for a user in the
+container to invoke operations on the init service in the same way it could if
+outside the container. This also applies to other applications in the host which
+use UNIX domain sockets in the filesystem, such as DBus, Libvirtd, and many
+more. If this is not desired, then applications should either specify the
+UID/GID mapping in the configuration to enable user namespaces and thus block
+access to the UNIX domain socket based on permissions, or should ensure the
+relevant directories have a bind mount to hide them. This is particularly
+important for the ``/run`` or ``/var/run`` directories.
+
+User and group isolation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the guest configuration does not list any ID mapping, then the user and group
+IDs used inside the container will match those used outside the container. In
+addition, the capabilities associated with a process in the container will infer
+the same privileges they would for a process in the host. This has obvious
+implications for security, since a root user inside the container will be able
+to access any file owned by root that is visible to the container, and perform
+more or less any privileged kernel operation. In the absence of additional
+protection from sVirt, this means that the root user inside a container is
+effectively as powerful as the root user in the host. There is no security
+isolation of the root user.
+
+The ID mapping facility was introduced to allow for stricter control over the
+privileges of users inside the container. It allows apps to define rules such as
+"user ID 0 in the container maps to user ID 1000 in the host". In addition the
+privileges associated with capabilities are somewhat reduced so that they cannot
+be used to escape from the container environment. A full description of user
+namespaces is outside the scope of this document, however LWN has `a good
+write-up on the topic <https://lwn.net/Articles/532593/>`__. From the libvirt
+point of view, the key thing to remember is that defining an ID mapping for
+users and groups in the container XML configuration causes libvirt to activate
+the user namespace feature.
+
+Location of configuration files
+-------------------------------
+
+The LXC driver comes with sane default values. However, during its
+initialization it reads a configuration file which offers system administrator
+to override some of that default. The file is located under
+``/etc/libvirt/lxc.conf``
+
+Systemd Socket Activation Integration
+-------------------------------------
+
+The libvirt LXC driver provides the ability to pass across pre-opened file
+descriptors when starting LXC guests. This allows for libvirt LXC to support
+systemd's `socket activation
+capability <http://0pointer.de/blog/projects/socket-activated-containers.html>`__,
+where an incoming client connection in the host OS will trigger the startup of a
+container, which runs another copy of systemd which gets passed the server
+socket, and then activates the actual service handler in the container.
+
+Let us assume that you already have a LXC guest created, running a systemd
+instance as PID 1 inside the container, which has an SSHD service configured.
+The goal is to automatically activate the container when the first SSH
+connection is made. The first step is to create a couple of unit files for the
+host OS systemd instance. The ``/etc/systemd/system/mycontainer.service`` unit
+file specifies how systemd will start the libvirt LXC container
+
+::
+
+ [Unit]
+ Description=My little container
+
+ [Service]
+ ExecStart=/usr/bin/virsh -c lxc:///system start --pass-fds 3 mycontainer
+ ExecStop=/usr/bin/virsh -c lxc:///system destroy mycontainer
+ Type=oneshot
+ RemainAfterExit=yes
+ KillMode=none
+
+The ``--pass-fds 3`` argument specifies that the file descriptor number 3 that
+``virsh`` inherits from systemd, is to be passed into the container. Since
+``virsh`` will exit immediately after starting the container, the
+``RemainAfterExit`` and ``KillMode`` settings must be altered from their
+defaults.
+
+Next, the ``/etc/systemd/system/mycontainer.socket`` unit file is created to get
+the host systemd to listen on port 23 for TCP connections. When this unit file
+is activated by the first incoming connection, it will cause the
+``mycontainer.service`` unit to be activated with the FD corresponding to the
+listening TCP socket passed in as FD 3.
+
+::
+
+ [Unit]
+ Description=The SSH socket of my little container
+
+ [Socket]
+ ListenStream=23
+
+Port 23 was picked here so that the container doesn't conflict with the host's
+SSH which is on the normal port 22. That's it in terms of host side
+configuration.
+
+Inside the container, the ``/etc/systemd/system/sshd.socket`` unit file must be
+created
+
+::
+
+ [Unit]
+ Description=SSH Socket for Per-Connection Servers
+
+ [Socket]
+ ListenStream=23
+ Accept=yes
+
+The ``ListenStream`` value listed in this unit file, must match the value used
+in the host file. When systemd in the container receives the pre-opened FD from
+libvirt during container startup, it looks at the ``ListenStream`` values to
+figure out which FD to give to which service. The actual service to start is
+defined by a correspondingly named ``/etc/systemd/system/sshd@.service``
+
+::
+
+ [Unit]
+ Description=SSH Per-Connection Server for %I
+
+ [Service]
+ ExecStart=-/usr/sbin/sshd -i
+ StandardInput=socket
+
+Finally, make sure this SSH service is set to start on boot of the container, by
+running the following command inside the container:
+
+::
+
+ # mkdir -p /etc/systemd/system/sockets.target.wants/
+ # ln -s /etc/systemd/system/sshd.socket /etc/systemd/system/sockets.target.wants/
+
+This example shows how to activate the container based on an incoming SSH
+connection. If the container was also configured to have an httpd service, it
+may be desirable to activate it upon either an httpd or a sshd connection
+attempt. In this case, the ``mycontainer.socket`` file in the host would simply
+list multiple socket ports. Inside the container a separate ``xxxxx.socket``
+file would need to be created for each service, with a corresponding
+``ListenStream`` value set.
+
+Container security
+------------------
+
+sVirt SELinux
+~~~~~~~~~~~~~
+
+In the absence of the "user" namespace being used, containers cannot be
+considered secure against exploits of the host OS. The sVirt SELinux driver
+provides a way to secure containers even when the "user" namespace is not
used.
+The cost is that writing a policy to allow execution of arbitrary OS is not
+practical. The SELinux sVirt policy is typically tailored to work with a simpler
+application confinement use case, as provided by the "libvirt-sandbox"
project.
+
+Auditing
+~~~~~~~~
+
+The LXC driver is integrated with libvirt's auditing subsystem, which causes
+audit messages to be logged whenever there is an operation performed against a
+container which has impact on host resources. So for example, start/stop, device
+hotplug will all log audit messages providing details about what action occurred
+and any resources associated with it. There are the following 3 types of audit
+messages
+
+- ``VIRT_MACHINE_ID`` - details of the SELinux process and image security
+ labels assigned to the container.
+- ``VIRT_CONTROL`` - details of an action / operation performed against a
+ container. There are the following types of operation
+
+ - ``op=start`` - a container has been started. Provides the machine name,
+ uuid and PID of the ``libvirt_lxc`` controller process
+ - ``op=init`` - the init PID of the container has been started. Provides the
+ machine name, uuid and PID of the ``libvirt_lxc`` controller process and
+ PID of the init process (in the host PID namespace)
+ - ``op=stop`` - a container has been stopped. Provides the machine name,
+ uuid
+
+- ``VIRT_RESOURCE`` - details of a host resource associated with a container
+ action.
+
+Device access
+~~~~~~~~~~~~~
+
+All containers are launched with the CAP_MKNOD capability cleared and removed
+from the bounding set. Libvirt will ensure that the /dev filesystem is
+pre-populated with all devices that a container is allowed to use. In addition,
+the cgroup "device" controller is configured to block read/write/mknod from
all
+devices except those that a container is authorized to use.
+
+Example configurations
+----------------------
+
+Example config version 1
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <domain type='lxc'>
+ <name>vm1</name>
+ <memory>500000</memory>
+ <os>
+ <type>exe</type>
+ <init>/bin/sh</init>
+ </os>
+ <vcpu>1</vcpu>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <emulator>/usr/libexec/libvirt_lxc</emulator>
+ <interface type='network'>
+ <source network='default'/>
+ </interface>
+ <console type='pty' />
+ </devices>
+ </domain>
+
+In the <emulator> element, be sure you specify the correct path to libvirt_lxc,
+if it does not live in /usr/libexec on your system.
+
+The next example assumes there is a private root filesystem (perhaps
+hand-crafted using busybox, or installed from media, debootstrap, whatever)
+under /opt/vm-1-root:
+
+::
+
+ <domain type='lxc'>
+ <name>vm1</name>
+ <memory>32768</memory>
+ <os>
+ <type>exe</type>
+ <init>/init</init>
+ </os>
+ <vcpu>1</vcpu>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <emulator>/usr/libexec/libvirt_lxc</emulator>
+ <filesystem type='mount'>
+ <source dir='/opt/vm-1-root'/>
+ <target dir='/'/>
+ </filesystem>
+ <interface type='network'>
+ <source network='default'/>
+ </interface>
+ <console type='pty' />
+ </devices>
+ </domain>
+
+Altering the available capabilities
+-----------------------------------
+
+By default the libvirt LXC driver drops some capabilities among which CAP_MKNOD.
+However :since:`since 1.2.6` libvirt can be told to keep or drop some
+capabilities using a domain configuration like the following:
+
+::
+
+ ...
+ <features>
+ <capabilities policy='default'>
+ <mknod state='on'/>
+ <sys_chroot state='off'/>
+ </capabilities>
+ </features>
+ ...
+
+The capabilities children elements are named after the capabilities as defined
+in ``man 7 capabilities``. An ``off`` state tells libvirt to drop the
+capability, while an ``on`` state will force to keep the capability even though
+this one is dropped by default.
+
+The ``policy`` attribute can be one of ``default``, ``allow`` or ``deny``. It
+defines the default rules for capabilities: either keep the default behavior
+that is dropping a few selected capabilities, or keep all capabilities or drop
+all capabilities. The interest of ``allow`` and ``deny`` is that they guarantee
+that all capabilities will be kept (or removed) even if new ones are added
+later.
+
+The following example, drops all capabilities but CAP_MKNOD:
+
+::
+
+ ...
+ <features>
+ <capabilities policy='deny'>
+ <mknod state='on'/>
+ </capabilities>
+ </features>
+ ...
+
+Note that allowing capabilities that are normally dropped by default can
+seriously affect the security of the container and the host.
+
+Inherit namespaces
+------------------
+
+Libvirt allows you to inherit the namespace from container/process just like lxc
+tools or docker provides to share the network namespace. The following can be
+used to share required namespaces. If we want to share only one then the other
+namespaces can be ignored. The netns option is specific to sharenet. It can be
+used in cases we want to use existing network namespace rather than creating new
+network namespace for the container. In this case privnet option will be
+ignored.
+
+::
+
+ <domain type='lxc'
xmlns:lxc='http://libvirt.org/schemas/domain/lxc/1.0'>
+ ...
+ <lxc:namespace>
+ <lxc:sharenet type='netns' value='red'/>
+ <lxc:shareuts type='name' value='container1'/>
+ <lxc:shareipc type='pid' value='12345'/>
+ </lxc:namespace>
+ </domain>
+
+The use of namespace passthrough requires libvirt >= 1.2.19
+
+Container usage / management
+----------------------------
+
+As with any libvirt virtualization driver, LXC containers can be managed via a
+wide variety of libvirt based tools. At the lowest level the ``virsh`` command
+can be used to perform many tasks, by passing the ``-c lxc:///system`` argument.
+As an alternative to repeating the URI with every command, the
+``LIBVIRT_DEFAULT_URI`` environment variable can be set to ``lxc:///system``.
+The examples that follow outline some common operations with virsh and LXC. For
+further details about usage of virsh consult its manual page.
+
+Defining (saving) container configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh define`` command takes an XML configuration document and loads it
+into libvirt, saving the configuration on disk
+
+::
+
+ # virsh -c lxc:///system define myguest.xml
+
+Viewing container configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh dumpxml`` command can be used to view the current XML configuration
+of a container. By default the XML output reflects the current state of the
+container. If the container is running, it is possible to explicitly request the
+persistent configuration, instead of the current live configuration using the
+``--inactive`` flag
+
+::
+
+ # virsh -c lxc:///system dumpxml myguest
+
+Starting containers
+~~~~~~~~~~~~~~~~~~~
+
+The ``virsh start`` command can be used to start a container from a previously
+defined persistent configuration
+
+::
+
+ # virsh -c lxc:///system start myguest
+
+It is also possible to start so called "transient" containers, which do not
+require a persistent configuration to be saved by libvirt, using the
+``virsh create`` command.
+
+::
+
+ # virsh -c lxc:///system create myguest.xml
+
+Stopping containers
+~~~~~~~~~~~~~~~~~~~
+
+The ``virsh shutdown`` command can be used to request a graceful shutdown of the
+container. By default this command will first attempt to send a message to the
+init process via the ``/dev/initctl`` device node. If no such device node
+exists, then it will send SIGTERM to PID 1 inside the container.
+
+::
+
+ # virsh -c lxc:///system shutdown myguest
+
+If the container does not respond to the graceful shutdown request, it can be
+forcibly stopped using the ``virsh destroy``
+
+::
+
+ # virsh -c lxc:///system destroy myguest
+
+Rebooting a container
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh reboot`` command can be used to request a graceful shutdown of the
+container. By default this command will first attempt to send a message to the
+init process via the ``/dev/initctl`` device node. If no such device node
+exists, then it will send SIGHUP to PID 1 inside the container.
+
+::
+
+ # virsh -c lxc:///system reboot myguest
+
+Undefining (deleting) a container configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh undefine`` command can be used to delete the persistent
+configuration of a container. If the guest is currently running, this will turn
+it into a "transient" guest.
+
+::
+
+ # virsh -c lxc:///system undefine myguest
+
+Connecting to a container console
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh console`` command can be used to connect to the text console
+associated with a container.
+
+::
+
+ # virsh -c lxc:///system console myguest
+
+If the container has been configured with multiple console devices, then the
+``--devname`` argument can be used to choose the console to connect to. In LXC,
+multiple consoles will be named as 'console0', 'console1',
'console2', etc.
+
+::
+
+ # virsh -c lxc:///system console myguest --devname console1
+
+Running commands in a container
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh lxc-enter-namespace`` command can be used to enter the namespaces
+and security context of a container and then execute an arbitrary command.
+
+::
+
+ # virsh -c lxc:///system lxc-enter-namespace myguest -- /bin/ls -al /dev
+
+Monitoring container utilization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virt-top`` command can be used to monitor the activity and resource
+utilization of all containers on a host
+
+::
+
+ # virt-top -c lxc:///system
+
+Converting LXC container configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-from-native`` command can be used to convert most of the LXC
+container configuration into a domain XML fragment
+
+::
+
+ # virsh -c lxc:///system domxml-from-native lxc-tools /var/lib/lxc/myguest/config
+
+This conversion has some limitations due to the fact that the domxml-from-native
+command output has to be independent of the host. Here are a few things to take
+care of before converting:
+
+- Replace the fstab file referenced by lxc.mount by the corresponding
+ lxc.mount.entry lines.
+- Replace all relative sizes of tmpfs mount entries to absolute sizes. Also
+ make sure that tmpfs entries all have a size option (default is 50%).
+- Define lxc.cgroup.memory.limit_in_bytes to properly limit the memory
+ available to the container. The conversion will use 64MiB as the default.
diff --git a/docs/meson.build b/docs/meson.build
index cfbde2a58d..fdf1714da8 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvlxc',
'drvnodedev',
'drvopenvz',
'drvsecret',
@@ -80,6 +79,7 @@ docs_rst_files = [
'drvch',
'drvesx',
'drvhyperv',
+ 'drvlxc',
'drvqemu',
'errors',
'formatbackup',
--
2.35.1
7:10 a.m.
New subject: [PATCH 07/29] docs: Convert 'drvnodedev' page to rST
Fix one cross link anchor along with the conversion.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvnodedev.html.in | 383 ----------------------------------------
docs/drvnodedev.rst | 348 ++++++++++++++++++++++++++++++++++++
docs/formatdomain.rst | 3 +-
docs/meson.build | 2 +-
4 files changed, 351 insertions(+), 385 deletions(-)
delete mode 100644 docs/drvnodedev.html.in
create mode 100644 docs/drvnodedev.rst
diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
deleted file mode 100644
index ee75eeb25c..0000000000
--- a/docs/drvnodedev.html.in
+++ /dev/null
@@ -1,383 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Host device management</h1>
-
- <p>
- Libvirt provides management of both physical and virtual host devices
- (historically also referred to as node devices) like USB, PCI, SCSI, and
- network devices. This also includes various virtualization capabilities
- which the aforementioned devices provide for utilization, for example
- SR-IOV, NPIV, MDEV, DRM, etc.
- </p>
-
- <p>
- The node device driver provides means to list and show details about host
- devices (<code>virsh nodedev-list</code>, <code>virsh
nodedev-info</code>,
- and <code>virsh nodedev-dumpxml</code>), which are generic and can be
used
- with all devices. It also provides the means to manage virtual devices.
- Persistently-defined virtual devices are only supported for mediated
- devices, while transient devices are supported by both mediated devices
- and NPIV (<a
href="https://wiki.libvirt.org/page/NPIV_in_libvirt">more
- info about NPIV)</a>).
- </p>
- <p>
- Persistent virtual devices are managed with
- <code>virsh nodedev-define</code> and <code>virsh
nodedev-undefine</code>.
- Persistent devices can be configured to start manually or automatically
- using <code>virsh nodedev-autostart</code>. Inactive devices can be
made
- active with <code>virsh nodedev-start</code>.
- </p>
- <p>
- Transient virtual devices are started and stopped with the commands
- <code>virsh nodedev-create</code> and <code>virsh
nodedev-destroy</code>.
- </p>
- <p>
- Devices on the host system are arranged in a tree-like hierarchy, with
- the root node being called <code>computer</code>. The node device
driver
- supports udev backend (HAL backend was removed in <code>6.8.0</code>).
- </p>
-
- <p>
- Details of the XML format of a host device can be found <a
- href="formatnode.html">here</a>. Of particular interest is the
- <code>capability</code> element, which describes features supported by
- the device. Some specific device types are addressed in more detail
- below.
- </p>
- <h2>Basic structure of a node device</h2>
- <pre>
-<device>
- <name>pci_0000_00_17_0</name>
- <path>/sys/devices/pci0000:00/0000:00:17.0</path>
- <parent>computer</parent>
- <driver>
- <name>ahci</name>
- </driver>
- <capability type='pci'>
-...
- </capability>
-</device></pre>
-
- <ul id="toc"/>
-
- <h2><a id="PCI">PCI host devices</a></h2>
- <dl>
- <dt><code>capability</code></dt>
- <dd>
- When used as top level element, the supported values for the
- <code>type</code> attribute are <code>pci</code> and
- <code>phys_function</code> (see <a
href="#SRIOVCap">SR-IOV below</a>).
- </dd>
- </dl>
- <pre>
-<device>
- <name>pci_0000_04_00_1</name>
-
<path>/sys/devices/pci0000:00/0000:00:06.0/0000:04:00.1</path>
- <parent>pci_0000_00_06_0</parent>
- <driver>
- <name>igb</name>
- </driver>
- <capability type='pci'>
- <domain>0</domain>
- <bus>4</bus>
- <slot>0</slot>
- <function>1</function>
- <product id='0x10c9'>82576 Gigabit Network
Connection</product>
- <vendor id='0x8086'>Intel Corporation</vendor>
- <iommuGroup number='15'>
- <address domain='0x0000' bus='0x04' slot='0x00'
function='0x1'/>
- </iommuGroup>
- <numa node='0'/>
- <pci-express>
- <link validity='cap' port='1' speed='2.5'
width='2'/>
- <link validity='sta' speed='2.5' width='2'/>
- </pci-express>
- </capability>
-</device></pre>
-
- <p>
- The XML format for a PCI device stays the same for any further
- capabilities it supports, a single nested
<code><capability></code>
- element will be included for each capability the device supports.
- </p>
-
- <h3><a id="SRIOVCap">SR-IOV capability</a></h3>
- <p>
- Single root input/output virtualization (SR-IOV) allows sharing of the
- PCIe resources by multiple virtual environments. That is achieved by
- slicing up a single full-featured physical resource called physical
- function (PF) into multiple devices called virtual functions (VFs) sharing
- their configuration with the underlying PF. Despite the SR-IOV
- specification, the amount of VFs that can be created on a PF varies among
- manufacturers.
- </p>
-
- <p>
- Suppose the NIC <a href="#PCI">above</a> was also SR-IOV
capable, it would
- also include a nested
- <code><capability></code> element enumerating all
virtual
- functions available on the physical device (physical port) like in the
- example below.
- </p>
-
- <pre>
-<capability type='pci'>
-...
- <capability type='virt_functions' maxCount='7'>
- <address domain='0x0000' bus='0x04' slot='0x10'
function='0x1'/>
- <address domain='0x0000' bus='0x04' slot='0x10'
function='0x3'/>
- <address domain='0x0000' bus='0x04' slot='0x10'
function='0x5'/>
- <address domain='0x0000' bus='0x04' slot='0x10'
function='0x7'/>
- <address domain='0x0000' bus='0x04' slot='0x11'
function='0x1'/>
- <address domain='0x0000' bus='0x04' slot='0x11'
function='0x3'/>
- <address domain='0x0000' bus='0x04' slot='0x11'
function='0x5'/>
- </capability>
-...
-</capability></pre>
- <p>
- A SR-IOV child device on the other hand, would then report its top level
- capability type as a <code>phys_function</code> instead:
- </p>
-
- <pre>
-<device>
-...
- <capability type='phys_function'>
- <address domain='0x0000' bus='0x04' slot='0x00'
function='0x0'/>
- </capability>
-...
-</device></pre>
-
- <h3><a id="MDEVCap">MDEV capability</a></h3>
- <p>
- A device capable of creating mediated devices will include a nested
- capability <code>mdev_types</code> which enumerates all supported mdev
- types on the physical device, along with the type attributes available
- through sysfs. A detailed description of the XML format for the
- <code>mdev_types</code> capability can be found
- <a href="formatnode.html#MDEVTypesCap">here</a>.
- </p>
- <p>
- The following example shows how we might represent an NVIDIA GPU device
- that supports mediated devices. See below for <a href="#MDEV">more
- information about mediated devices</a>.
- </p>
-
-<pre>
-<device>
-...
- <driver>
- <name>nvidia</name>
- </driver>
- <capability type='pci'>
-...
- <capability type='mdev_types'>
- <type id='nvidia-11'>
- <name>GRID M60-0B</name>
- <deviceAPI>vfio-pci</deviceAPI>
- <availableInstances>16</availableInstances>
- </type>
- <!-- Here would come the rest of the available mdev types -->
- </capability>
-...
- </capability>
-</device></pre>
-
- <h3><a id="VPDCap">VPD capability</a></h3>
- <p>
- A device that exposes a PCI/PCIe VPD capability will include a nested
- capability <code>vpd</code> which presents data stored in the Vital
Product
- Data (VPD). VPD provides a device name and a number of other standard-defined
- read-only fields (change level, manufacture id, part number, serial number) and
- vendor-specific read-only fields. Additionally, if a device supports it,
- read-write fields (asset tag, vendor-specific fields or system fields) may
- also be present. The VPD capability is optional for PCI/PCIe devices and the
- set of exposed fields may vary depending on a device. The XML format follows
- the binary format described in "I.3. VPD Definitions" in PCI Local Bus
(2.2+)
- and the identical format in PCIe 4.0+. At the time of writing, the support for
- exposing this capability is only present on Linux-based systems (kernel version
- v2.6.26 is the first one to expose VPD via sysfs which Libvirt relies on).
- Reading the VPD contents requires root privileges, therefore,
- <code>virsh nodedev-dumpxml</code> must be executed accordingly.
- A description of the XML format for the <code>vpd</code> capability
can
- be found <a href="formatnode.html#VPDCap">here</a>.
- </p>
- <p>
- The following example shows a VPD representation for a device that exposes the
- VPD capability with read-only and read-write fields. Among other things,
- the VPD of this particular device includes a unique board serial number.
- </p>
-<pre>
-<device>
- <name>pci_0000_42_00_0</name>
- <capability type='pci'>
- <class>0x020000</class>
- <domain>0</domain>
- <bus>66</bus>
- <slot>0</slot>
- <function>0</function>
- <product id='0xa2d6'>MT42822 BlueField-2 integrated
ConnectX-6 Dx network controller</product>
- <vendor id='0x15b3'>Mellanox
Technologies</vendor>
- <capability type='virt_functions'
maxCount='16'/>
- <capability type='vpd'>
- <name>BlueField-2 DPU 25GbE Dual-Port SFP56, Crypto Enabled, 16GB
on-board DDR, 1GbE OOB management, Tall Bracket</name>
- <fields access='readonly'>
- <change_level>B1</change_level>
- <manufacture_id>foobar</manufacture_id>
- <part_number>MBF2H332A-AEEOT</part_number>
- <serial_number>MT2113X00000</serial_number>
- <vendor_field index='0'>PCIeGen4
x8</vendor_field>
- <vendor_field
index='2'>MBF2H332A-AEEOT</vendor_field>
- <vendor_field
index='3'>3c53d07eec484d8aab34dabd24fe575aa</vendor_field>
- <vendor_field
index='A'>MLX:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0:MODL=BF2H332A</vendor_field>
- </fields>
- <fields access='readwrite'>
- <asset_tag>fooasset</asset_tag>
- <vendor_field
index='0'>vendorfield0</vendor_field>
- <vendor_field
index='2'>vendorfield2</vendor_field>
- <vendor_field
index='A'>vendorfieldA</vendor_field>
- <system_field
index='B'>systemfieldB</system_field>
- <system_field
index='0'>systemfield0</system_field>
- </fields>
- </capability>
- <iommuGroup number='65'>
- <address domain='0x0000' bus='0x42'
slot='0x00' function='0x0'/>
- </iommuGroup>
- <numa node='0'/>
- <pci-express>
- <link validity='cap' port='0'
speed='16' width='8'/>
- <link validity='sta' speed='8'
width='8'/>
- </pci-express>
- </capability>
-</device>
-</pre>
-
- <h2><a id="MDEV">Mediated devices (MDEVs)</a></h2>
- <p>
- Mediated devices (<span class="since">Since 3.2.0</span>) are
software
- devices defining resource allocation on the backing physical device which
- in turn allows the parent physical device's resources to be divided into
- several mediated devices, thus sharing the physical device's performance
- among multiple guests. Unlike SR-IOV however, where a PCIe device appears
- as multiple separate PCIe devices on the host's PCI bus, mediated devices
- only appear on the mdev virtual bus. Therefore, no detach/reattach
- procedure from/to the host driver procedure is involved even though
- mediated devices are used in a direct device assignment manner. A
- detailed description of the XML format for the <code>mdev</code>
- capability can be found <a
href="formatnode.html#mdev">here</a>.
- </p>
-
- <h3>Example of a mediated device</h3>
- <pre>
-<device>
- <name>mdev_4b20d080_1b54_4048_85b3_a6a62d165c01</name>
-
<path>/sys/devices/pci0000:00/0000:00:02.0/4b20d080-1b54-4048-85b3-a6a62d165c01</path>
- <parent>pci_0000_06_00_0</parent>
- <driver>
- <name>vfio_mdev</name>
- </driver>
- <capability type='mdev'>
- <type id='nvidia-11'/>
- <uuid>4b20d080-1b54-4048-85b3-a6a62d165c01</uuid>
- <iommuGroup number='12'/>
- </capability>
-</device></pre>
-
- <p>
- The support of mediated device's framework in libvirt's node device driver
- covers the following features:
- </p>
-
- <ul>
- <li>
- list available mediated devices on the host
- (<span class="since">Since 3.4.0</span>)
- </li>
- <li>
- display device details
- (<span class="since">Since 3.4.0</span>)
- </li>
- <li>
- create transient mediated devices
- (<span class="since">Since 6.5.0</span>)
- </li>
- <li>
- define persistent mediated devices
- (<span class="since">Since 7.3.0</span>)
- </li>
- </ul>
-
- <p>
- Because mediated devices are instantiated from vendor specific templates,
- simply called 'types', information describing these types is contained
- within the parent device's capabilities (see the example in <a
- href="#PCI">PCI host devices</a>). To list all devices capable
of
- creating mediated devices, the following command can be used.
- </p>
- <pre>$ virsh nodedev-list --cap mdev_types</pre>
-
- <p>
- To see the supported mediated device types on a specific physical device
- use the following:
- </p>
-
- <pre>$ virsh nodedev-dumpxml <device></pre>
-
- <p>
- Before creating a mediated device, unbind the device from the respective
- device driver, eg. subchannel I/O driver for a CCW device. Then bind the
- device to the respective VFIO driver. For a CCW device, also unbind the
- corresponding subchannel of the CCW device from the subchannel I/O driver
- and then bind the subchannel (instead of the CCW device) to the vfio_ccw
- driver. The below example shows the unbinding and binding steps for a CCW
- device.
- </p>
-
- <pre>
-device="0.0.1234"
-subchannel="0.0.0123"
-echo $device > /sys/bus/ccw/devices/$device/driver/unbind
-echo $subchannel > /sys/bus/css/devices/$subchannel/driver/unbind
-echo $subchannel > /sys/bus/css/drivers/vfio_ccw/bind
- </pre>
-
- <p>
- To instantiate a transient mediated device, create an XML file representing the
- device. See above for information about the mediated device xml format.
- </p>
-
- <pre>$ virsh nodedev-create <xml-file>
-Node device '<device-name>' created from
'<xml-file>'</pre>
-
- <p>
- If you would like to persistently define the device so that it will be
- maintained across host reboots, use <code>virsh nodedev-define</code>
- instead of <code>nodedev-create</code>:
- </p>
-
- <pre>$ virsh nodedev-define <xml-file>
-Node device '<device-name>' defined from
'<xml-file>'</pre>
-
- <p>
- To start an instance of this device definition, use the following command:
- </p>
-
- <pre>$ virsh nodedev-start <device-name></pre>
- <p>
- Active mediated device instances can be stopped using <code>virsh
- nodedev-destroy</code>, and persistent device definitions can be removed
- using <code>virsh nodedev-undefine</code>.
- </p>
-
- <p>
- If a mediated device is defined persistently, it can also be set to be
- automatically started whenever the host reboots or when the parent device
- becomes available. In order to autostart a mediated device, use the
- following command:
- </p>
-
- <pre>$ virsh nodedev-autostart <device-name></pre>
- </body>
-</html>
diff --git a/docs/drvnodedev.rst b/docs/drvnodedev.rst
new file mode 100644
index 0000000000..cddb36c73b
--- /dev/null
+++ b/docs/drvnodedev.rst
@@ -0,0 +1,348 @@
+.. role:: since
+
+======================
+Host device management
+======================
+
+.. contents::
+
+Libvirt provides management of both physical and virtual host devices
+(historically also referred to as node devices) like USB, PCI, SCSI, and network
+devices. This also includes various virtualization capabilities which the
+aforementioned devices provide for utilization, for example SR-IOV, NPIV, MDEV,
+DRM, etc.
+
+The node device driver provides means to list and show details about host
+devices (``virsh nodedev-list``, ``virsh nodedev-info``, and
+``virsh nodedev-dumpxml``), which are generic and can be used with all devices.
+It also provides the means to manage virtual devices. Persistently-defined
+virtual devices are only supported for mediated devices, while transient devices
+are supported by both mediated devices and NPIV (`more info about
+NPIV) <https://wiki.libvirt.org/page/NPIV_in_libvirt>`__).
+
+Persistent virtual devices are managed with ``virsh nodedev-define`` and
+``virsh nodedev-undefine``. Persistent devices can be configured to start
+manually or automatically using ``virsh nodedev-autostart``. Inactive devices
+can be made active with ``virsh nodedev-start``.
+
+Transient virtual devices are started and stopped with the commands
+``virsh nodedev-create`` and ``virsh nodedev-destroy``.
+
+Devices on the host system are arranged in a tree-like hierarchy, with the root
+node being called ``computer``. The node device driver supports udev backend
+(HAL backend was removed in ``6.8.0``).
+
+Details of the XML format of a host device can be found
+`here <formatnode.html>`__. Of particular interest is the ``capability``
+element, which describes features supported by the device. Some specific device
+types are addressed in more detail below.
+
+Basic structure of a node device
+--------------------------------
+
+::
+
+ <device>
+ <name>pci_0000_00_17_0</name>
+ <path>/sys/devices/pci0000:00/0000:00:17.0</path>
+ <parent>computer</parent>
+ <driver>
+ <name>ahci</name>
+ </driver>
+ <capability type='pci'>
+ ...
+ </capability>
+ </device>
+
+PCI host devices
+----------------
+
+``capability``
+ When used as top level element, the supported values for the ``type``
+ attribute are ``pci`` and ``phys_function`` (see `SR-IOV
+ below <#SRIOVCap>`__).
+
+::
+
+ <device>
+ <name>pci_0000_04_00_1</name>
+ <path>/sys/devices/pci0000:00/0000:00:06.0/0000:04:00.1</path>
+ <parent>pci_0000_00_06_0</parent>
+ <driver>
+ <name>igb</name>
+ </driver>
+ <capability type='pci'>
+ <domain>0</domain>
+ <bus>4</bus>
+ <slot>0</slot>
+ <function>1</function>
+ <product id='0x10c9'>82576 Gigabit Network
Connection</product>
+ <vendor id='0x8086'>Intel Corporation</vendor>
+ <iommuGroup number='15'>
+ <address domain='0x0000' bus='0x04' slot='0x00'
function='0x1'/>
+ </iommuGroup>
+ <numa node='0'/>
+ <pci-express>
+ <link validity='cap' port='1' speed='2.5'
width='2'/>
+ <link validity='sta' speed='2.5' width='2'/>
+ </pci-express>
+ </capability>
+ </device>
+
+The XML format for a PCI device stays the same for any further capabilities it
+supports, a single nested ``<capability>`` element will be included for each
+capability the device supports.
+
+SR-IOV capability
+~~~~~~~~~~~~~~~~~
+
+Single root input/output virtualization (SR-IOV) allows sharing of the PCIe
+resources by multiple virtual environments. That is achieved by slicing up a
+single full-featured physical resource called physical function (PF) into
+multiple devices called virtual functions (VFs) sharing their configuration with
+the underlying PF. Despite the SR-IOV specification, the amount of VFs that can
+be created on a PF varies among manufacturers.
+
+Suppose the NIC `above <#PCI>`__ was also SR-IOV capable, it would also include
+a nested ``<capability>`` element enumerating all virtual functions available on
+the physical device (physical port) like in the example below.
+
+::
+
+ <capability type='pci'>
+ ...
+ <capability type='virt_functions' maxCount='7'>
+ <address domain='0x0000' bus='0x04' slot='0x10'
function='0x1'/>
+ <address domain='0x0000' bus='0x04' slot='0x10'
function='0x3'/>
+ <address domain='0x0000' bus='0x04' slot='0x10'
function='0x5'/>
+ <address domain='0x0000' bus='0x04' slot='0x10'
function='0x7'/>
+ <address domain='0x0000' bus='0x04' slot='0x11'
function='0x1'/>
+ <address domain='0x0000' bus='0x04' slot='0x11'
function='0x3'/>
+ <address domain='0x0000' bus='0x04' slot='0x11'
function='0x5'/>
+ </capability>
+ ...
+ </capability>
+
+A SR-IOV child device on the other hand, would then report its top level
+capability type as a ``phys_function`` instead:
+
+::
+
+ <device>
+ ...
+ <capability type='phys_function'>
+ <address domain='0x0000' bus='0x04' slot='0x00'
function='0x0'/>
+ </capability>
+ ...
+ </device>
+
+MDEV capability
+~~~~~~~~~~~~~~~
+
+A device capable of creating mediated devices will include a nested capability
+``mdev_types`` which enumerates all supported mdev types on the physical device,
+along with the type attributes available through sysfs. A detailed description
+of the XML format for the ``mdev_types`` capability can be found
+`here <formatnode.html#MDEVTypesCap>`__.
+
+The following example shows how we might represent an NVIDIA GPU device that
+supports mediated devices. See below for `more information about mediated
+devices <#MDEV>`__.
+
+::
+
+ <device>
+ ...
+ <driver>
+ <name>nvidia</name>
+ </driver>
+ <capability type='pci'>
+ ...
+ <capability type='mdev_types'>
+ <type id='nvidia-11'>
+ <name>GRID M60-0B</name>
+ <deviceAPI>vfio-pci</deviceAPI>
+ <availableInstances>16</availableInstances>
+ </type>
+ <!-- Here would come the rest of the available mdev types -->
+ </capability>
+ ...
+ </capability>
+ </device>
+
+VPD capability
+~~~~~~~~~~~~~~
+
+A device that exposes a PCI/PCIe VPD capability will include a nested capability
+``vpd`` which presents data stored in the Vital Product Data (VPD). VPD provides
+a device name and a number of other standard-defined read-only fields (change
+level, manufacture id, part number, serial number) and vendor-specific read-only
+fields. Additionally, if a device supports it, read-write fields (asset tag,
+vendor-specific fields or system fields) may also be present. The VPD capability
+is optional for PCI/PCIe devices and the set of exposed fields may vary
+depending on a device. The XML format follows the binary format described in
+"I.3. VPD Definitions" in PCI Local Bus (2.2+) and the identical format in
PCIe
+4.0+. At the time of writing, the support for exposing this capability is only
+present on Linux-based systems (kernel version v2.6.26 is the first one to
+expose VPD via sysfs which Libvirt relies on). Reading the VPD contents requires
+root privileges, therefore, ``virsh nodedev-dumpxml`` must be executed
+accordingly. A description of the XML format for the ``vpd`` capability can be
+found `here <formatnode.html#VPDCap>`__.
+
+The following example shows a VPD representation for a device that exposes the
+VPD capability with read-only and read-write fields. Among other things, the VPD
+of this particular device includes a unique board serial number.
+
+::
+
+ <device>
+ <name>pci_0000_42_00_0</name>
+ <capability type='pci'>
+ <class>0x020000</class>
+ <domain>0</domain>
+ <bus>66</bus>
+ <slot>0</slot>
+ <function>0</function>
+ <product id='0xa2d6'>MT42822 BlueField-2 integrated ConnectX-6 Dx
network controller</product>
+ <vendor id='0x15b3'>Mellanox Technologies</vendor>
+ <capability type='virt_functions' maxCount='16'/>
+ <capability type='vpd'>
+ <name>BlueField-2 DPU 25GbE Dual-Port SFP56, Crypto Enabled, 16GB on-board
DDR, 1GbE OOB management, Tall Bracket</name>
+ <fields access='readonly'>
+ <change_level>B1</change_level>
+ <manufacture_id>foobar</manufacture_id>
+ <part_number>MBF2H332A-AEEOT</part_number>
+ <serial_number>MT2113X00000</serial_number>
+ <vendor_field index='0'>PCIeGen4 x8</vendor_field>
+ <vendor_field index='2'>MBF2H332A-AEEOT</vendor_field>
+ <vendor_field
index='3'>3c53d07eec484d8aab34dabd24fe575aa</vendor_field>
+ <vendor_field
index='A'>MLX:MN=MLNX:CSKU=V2:UUID=V3:PCI=V0:MODL=BF2H332A</vendor_field>
+ </fields>
+ <fields access='readwrite'>
+ <asset_tag>fooasset</asset_tag>
+ <vendor_field index='0'>vendorfield0</vendor_field>
+ <vendor_field index='2'>vendorfield2</vendor_field>
+ <vendor_field index='A'>vendorfieldA</vendor_field>
+ <system_field index='B'>systemfieldB</system_field>
+ <system_field index='0'>systemfield0</system_field>
+ </fields>
+ </capability>
+ <iommuGroup number='65'>
+ <address domain='0x0000' bus='0x42' slot='0x00'
function='0x0'/>
+ </iommuGroup>
+ <numa node='0'/>
+ <pci-express>
+ <link validity='cap' port='0' speed='16'
width='8'/>
+ <link validity='sta' speed='8' width='8'/>
+ </pci-express>
+ </capability>
+ </device>
+
+Mediated devices (MDEVs)
+------------------------
+
+Mediated devices ( :since:`Since 3.2.0` ) are software devices defining resource
+allocation on the backing physical device which in turn allows the parent
+physical device's resources to be divided into several mediated devices, thus
+sharing the physical device's performance among multiple guests. Unlike SR-IOV
+however, where a PCIe device appears as multiple separate PCIe devices on the
+host's PCI bus, mediated devices only appear on the mdev virtual bus. Therefore,
+no detach/reattach procedure from/to the host driver procedure is involved even
+though mediated devices are used in a direct device assignment manner. A
+detailed description of the XML format for the ``mdev`` capability can be found
+`here <formatnode.html#mdev>`__.
+
+Example of a mediated device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ <device>
+ <name>mdev_4b20d080_1b54_4048_85b3_a6a62d165c01</name>
+
<path>/sys/devices/pci0000:00/0000:00:02.0/4b20d080-1b54-4048-85b3-a6a62d165c01</path>
+ <parent>pci_0000_06_00_0</parent>
+ <driver>
+ <name>vfio_mdev</name>
+ </driver>
+ <capability type='mdev'>
+ <type id='nvidia-11'/>
+ <uuid>4b20d080-1b54-4048-85b3-a6a62d165c01</uuid>
+ <iommuGroup number='12'/>
+ </capability>
+ </device>
+
+The support of mediated device's framework in libvirt's node device driver
+covers the following features:
+
+- list available mediated devices on the host ( :since:`Since 3.4.0` )
+- display device details ( :since:`Since 3.4.0` )
+- create transient mediated devices ( :since:`Since 6.5.0` )
+- define persistent mediated devices ( :since:`Since 7.3.0` )
+
+Because mediated devices are instantiated from vendor specific templates, simply
+called 'types', information describing these types is contained within the
+parent device's capabilities (see the example in `PCI host devices <#PCI>`__).
+To list all devices capable of creating mediated devices, the following command
+can be used.
+
+::
+
+ $ virsh nodedev-list --cap mdev_types
+
+To see the supported mediated device types on a specific physical device use the
+following:
+
+::
+
+ $ virsh nodedev-dumpxml <device>
+
+Before creating a mediated device, unbind the device from the respective device
+driver, eg. subchannel I/O driver for a CCW device. Then bind the device to the
+respective VFIO driver. For a CCW device, also unbind the corresponding
+subchannel of the CCW device from the subchannel I/O driver and then bind the
+subchannel (instead of the CCW device) to the vfio_ccw driver. The below example
+shows the unbinding and binding steps for a CCW device.
+
+::
+
+ device="0.0.1234"
+ subchannel="0.0.0123"
+ echo $device > /sys/bus/ccw/devices/$device/driver/unbind
+ echo $subchannel > /sys/bus/css/devices/$subchannel/driver/unbind
+ echo $subchannel > /sys/bus/css/drivers/vfio_ccw/bind
+
+To instantiate a transient mediated device, create an XML file representing the
+device. See above for information about the mediated device xml format.
+
+::
+
+ $ virsh nodedev-create <xml-file>
+ Node device '<device-name>' created from '<xml-file>'
+
+If you would like to persistently define the device so that it will be
+maintained across host reboots, use ``virsh nodedev-define`` instead of
+``nodedev-create``:
+
+::
+
+ $ virsh nodedev-define <xml-file>
+ Node device '<device-name>' defined from '<xml-file>'
+
+To start an instance of this device definition, use the following command:
+
+::
+
+ $ virsh nodedev-start <device-name>
+
+Active mediated device instances can be stopped using
+``virsh nodedev-destroy``, and persistent device definitions can be
+removed using ``virsh nodedev-undefine``.
+
+If a mediated device is defined persistently, it can also be set to be
+automatically started whenever the host reboots or when the parent device
+becomes available. In order to autostart a mediated device, use the following
+command:
+
+::
+
+ $ virsh nodedev-autostart <device-name>
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index e492532004..4fb2e1a9f4 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -4166,7 +4166,8 @@ or:
specifies the device API which determines how the host's vfio driver will
expose the device to the guest. Currently, ``model='vfio-pci'``,
``model='vfio-ccw'`` ( :since:`Since 4.4.0` ) and
``model='vfio-ap'`` (
- :since:`Since 4.9.0` ) is supported. `MDEV <drvnodedev.html#MDEV>`__
+ :since:`Since 4.9.0` ) is supported.
+ `MDEV <drvnodedev.html#mediated-devices-mdevs>`__
section provides more information about mediated devices as well as how to
create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)` an
optional ``display`` attribute may be used to enable or disable support
diff --git a/docs/meson.build b/docs/meson.build
index fdf1714da8..bf5a978b07 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvnodedev',
'drvopenvz',
'drvsecret',
'drvtest',
@@ -80,6 +79,7 @@ docs_rst_files = [
'drvesx',
'drvhyperv',
'drvlxc',
+ 'drvnodedev',
'drvqemu',
'errors',
'formatbackup',
--
2.35.1
7:58 a.m.
New subject: [PATCH 07/29] docs: Convert 'drvnodedev' page to rST
On Mon, Mar 28, 2022 at 02:10:22PM +0200, Peter Krempa wrote:
Fix one cross link anchor along with the conversion.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 a.m.
New subject: [PATCH 08/29] docs: Convert 'drvopenvz' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvopenvz.html.in | 123 -----------------------------------------
docs/drvopenvz.rst | 97 ++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 98 insertions(+), 124 deletions(-)
delete mode 100644 docs/drvopenvz.html.in
create mode 100644 docs/drvopenvz.rst
diff --git a/docs/drvopenvz.html.in b/docs/drvopenvz.html.in
deleted file mode 100644
index 64a75e3fec..0000000000
--- a/docs/drvopenvz.html.in
+++ /dev/null
@@ -1,123 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>OpenVZ container driver</h1>
-
- <ul id="toc"></ul>
-
- <p>
- The OpenVZ driver for libvirt allows use and management of container
- based virtualization on a Linux host OS. Prior to using the OpenVZ
- driver, the OpenVZ enabled kernel must be installed & booted, and the
- OpenVZ userspace tools installed. The libvirt driver has been tested
- with OpenVZ 3.0.22, but other 3.0.x versions should also work without
- undue trouble.
- </p>
-
- <h2><a id="project">Project Links</a></h2>
-
- <ul>
- <li>
- The <a href="https://openvz.org/">OpenVZ</a> Linux
container
- system
- </li>
- </ul>
-
- <h2><a id="connections">Connections to OpenVZ
driver</a></h2>
-
- <p>
- The libvirt OpenVZ driver is a single-instance privileged driver,
- with a driver name of 'openvz'. Some example connection URIs for
- the libvirt driver are:
- </p>
-
-<pre>
-openvz:///system (local access)
-openvz+unix:///system (local access)
-openvz://example.com/system (remote access, TLS/x509)
-openvz+tcp://example.com/system (remote access, SASl/Kerberos)
-openvz+ssh://root@example.com/system (remote access, SSH tunnelled)
-</pre>
-
- <h2><a id="notes">Notes on bridged
networking</a></h2>
-
- <p>
- Bridged networking enables a guest domain (ie container) to have its
- network interface connected directly to the host's physical LAN. Before
- this can be used there are a couple of configuration pre-requisites for
- the host OS.
- </p>
-
- <h3><a id="host">Host network devices</a></h3>
-
- <p>
- One or more of the physical devices must be attached to a bridge. The
- process for this varies according to the operating system in use, so
- for up to date notes consult the <a
href="https://wiki.libvirt.org">Wiki</a>
- or your operating system's networking documentation. The basic idea is
- that the host OS should end up with a bridge device "br0" containing a
- physical device "eth0", or a bonding device "bond0".
- </p>
-
- <h3><a id="tools">OpenVZ tools
configuration</a></h3>
-
- <p>
- OpenVZ releases later than 3.0.23 ship with a standard network device
- setup script that is able to setup bridging, named
- <code>/usr/sbin/vznetaddbr</code>. For releases prior to 3.0.23, this
- script must be created manually by the host OS administrator. The
- simplest way is to just download the latest version of this script
- from a newer OpenVZ release, or upstream source repository. Then
- a generic configuration file <code>/etc/vz/vznet.conf</code>
- must be created containing
- </p>
-
-<pre>
-#!/bin/bash
-EXTERNAL_SCRIPT="/usr/sbin/vznetaddbr"
-</pre>
-
- <p>
- The host OS is now ready to allow bridging of guest containers, which
- will work whether the container is started with libvirt, or OpenVZ
- tools.
- </p>
-
-
- <h2><a id="example">Example guest domain XML
configuration</a></h2>
-
- <p>
- The current libvirt OpenVZ driver has a restriction that the
- domain names must match the OpenVZ container VEID, which by
- convention start at 100, and are incremented from there. The
- choice of OS template to use inside the container is determined
- by the <code>filesystem</code> tag, and the template source name
- matches the templates known to OpenVZ tools.
- </p>
-
-<pre>
-<domain type='openvz' id='104'>
- <name>104</name>
- <uuid>86c12009-e591-a159-6e9f-91d18b85ef78</uuid>
- <vcpu>3</vcpu>
- <os>
- <type>exe</type>
- <init>/sbin/init</init>
- </os>
- <devices>
- <filesystem type='template'>
- <source name='fedora-9-i386-minimal'/>
- <target dir='/'/>
- </filesystem>
- <interface type='bridge'>
- <mac address='00:18:51:5b:ea:bf'/>
- <source bridge='br0'/>
- <target dev='veth101.0'/>
- </interface>
- </devices>
-</domain>
-</pre>
-
- </body>
-</html>
diff --git a/docs/drvopenvz.rst b/docs/drvopenvz.rst
new file mode 100644
index 0000000000..ff6e1f994d
--- /dev/null
+++ b/docs/drvopenvz.rst
@@ -0,0 +1,97 @@
+=======================
+OpenVZ container driver
+=======================
+
+.. contents::
+
+The OpenVZ driver for libvirt allows use and management of container based
+virtualization on a Linux host OS. Prior to using the OpenVZ driver, the OpenVZ
+enabled kernel must be installed & booted, and the OpenVZ userspace tools
+installed. The libvirt driver has been tested with OpenVZ 3.0.22, but other
+3.0.x versions should also work without undue trouble.
+
+Project Links
+-------------
+
+- The `OpenVZ <https://openvz.org/>`__ Linux container system
+
+Connections to OpenVZ driver
+----------------------------
+
+The libvirt OpenVZ driver is a single-instance privileged driver, with a driver
+name of 'openvz'. Some example connection URIs for the libvirt driver are:
+
+::
+
+ openvz:///system (local access)
+ openvz+unix:///system (local access)
+ openvz://example.com/system (remote access, TLS/x509)
+ openvz+tcp://example.com/system (remote access, SASl/Kerberos)
+ openvz+ssh://root@example.com/system (remote access, SSH tunnelled)
+
+Notes on bridged networking
+---------------------------
+
+Bridged networking enables a guest domain (ie container) to have its network
+interface connected directly to the host's physical LAN. Before this can be used
+there are a couple of configuration pre-requisites for the host OS.
+
+Host network devices
+~~~~~~~~~~~~~~~~~~~~
+
+One or more of the physical devices must be attached to a bridge. The process
+for this varies according to the operating system in use, so for up to date
+notes consult the `Wiki <https://wiki.libvirt.org>`__ or your operating
system's
+networking documentation. The basic idea is that the host OS should end up with
+a bridge device "br0" containing a physical device "eth0", or a
bonding device
+"bond0".
+
+OpenVZ tools configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenVZ releases later than 3.0.23 ship with a standard network device setup
+script that is able to setup bridging, named ``/usr/sbin/vznetaddbr``. For
+releases prior to 3.0.23, this script must be created manually by the host OS
+administrator. The simplest way is to just download the latest version of this
+script from a newer OpenVZ release, or upstream source repository. Then a
+generic configuration file ``/etc/vz/vznet.conf`` must be created containing
+
+::
+
+ #!/bin/bash
+ EXTERNAL_SCRIPT="/usr/sbin/vznetaddbr"
+
+The host OS is now ready to allow bridging of guest containers, which will work
+whether the container is started with libvirt, or OpenVZ tools.
+
+Example guest domain XML configuration
+--------------------------------------
+
+The current libvirt OpenVZ driver has a restriction that the domain names must
+match the OpenVZ container VEID, which by convention start at 100, and are
+incremented from there. The choice of OS template to use inside the container is
+determined by the ``filesystem`` tag, and the template source name matches the
+templates known to OpenVZ tools.
+
+::
+
+ <domain type='openvz' id='104'>
+ <name>104</name>
+ <uuid>86c12009-e591-a159-6e9f-91d18b85ef78</uuid>
+ <vcpu>3</vcpu>
+ <os>
+ <type>exe</type>
+ <init>/sbin/init</init>
+ </os>
+ <devices>
+ <filesystem type='template'>
+ <source name='fedora-9-i386-minimal'/>
+ <target dir='/'/>
+ </filesystem>
+ <interface type='bridge'>
+ <mac address='00:18:51:5b:ea:bf'/>
+ <source bridge='br0'/>
+ <target dev='veth101.0'/>
+ </interface>
+ </devices>
+ </domain>
diff --git a/docs/meson.build b/docs/meson.build
index bf5a978b07..d936091091 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvopenvz',
'drvsecret',
'drvtest',
'drvvbox',
@@ -80,6 +79,7 @@ docs_rst_files = [
'drvhyperv',
'drvlxc',
'drvnodedev',
+ 'drvopenvz',
'drvqemu',
'errors',
'formatbackup',
--
2.35.1
7:10 a.m.
New subject: [PATCH 09/29] docs: Convert 'drvsecret' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvsecret.html.in | 82 ------------------------------------------
docs/drvsecret.rst | 65 +++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 66 insertions(+), 83 deletions(-)
delete mode 100644 docs/drvsecret.html.in
create mode 100644 docs/drvsecret.rst
diff --git a/docs/drvsecret.html.in b/docs/drvsecret.html.in
deleted file mode 100644
index 1bd7d75215..0000000000
--- a/docs/drvsecret.html.in
+++ /dev/null
@@ -1,82 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Secret information management</h1>
-
- <p>
- The secrets driver in libvirt provides a simple interface for
- storing and retrieving secret information.
- </p>
-
- <h2><a id="uris">Connections to SECRET
driver</a></h2>
-
- <p>
- The libvirt SECRET driver is a multi-instance driver, providing a single
- system wide privileged driver (the "system" instance), and per-user
- unprivileged drivers (the "session" instance). A connection to the secret
- driver is automatically available when opening a connection to one of the
- stateful primary hypervisor drivers. It is none the less also possible to
- explicitly open just the secret driver, using the URI protocol "secret"
- Some example connection URIs for the driver are:
- </p>
-
-<pre>
-secret:///session (local access to per-user instance)
-secret+unix:///session (local access to per-user instance)
-
-secret:///system (local access to system instance)
-secret+unix:///system (local access to system instance)
-secret://example.com/system (remote access, TLS/x509)
-secret+tcp://example.com/system (remote access, SASl/Kerberos)
-secret+ssh://root@example.com/system (remote access, SSH tunnelled)
-</pre>
-
- <h3><a id="uriembedded">Embedded driver</a></h3>
-
- <p>
- Since 6.1.0 the secret driver has experimental support for operating
- in an embedded mode. In this scenario, rather than connecting to
- the libvirtd daemon, the secret driver runs in the client application
- process directly. 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.
- </p>
-
- <pre>
- secret:///embed?root=/some/dir
- </pre>
-
- <p>
- Under the specified root directory the following locations will
- be used
- </p>
-
- <pre>
-/some/dir
- |
- +- etc
- | |
- | +- secrets
- |
- +- run
- |
- +- secrets
- </pre>
-
- <p>
- 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>
-
- <p>
- 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. Normal practice would be to open the secret driver in embedded
- mode any time one of the other drivers is opened in embedded mode so
- that the two drivers can interact in-process.
- </p>
- </body>
-</html>
diff --git a/docs/drvsecret.rst b/docs/drvsecret.rst
new file mode 100644
index 0000000000..76a9097d2b
--- /dev/null
+++ b/docs/drvsecret.rst
@@ -0,0 +1,65 @@
+=============================
+Secret information management
+=============================
+
+The secrets driver in libvirt provides a simple interface for storing and
+retrieving secret information.
+
+Connections to SECRET driver
+----------------------------
+
+The libvirt SECRET driver is a multi-instance driver, providing a single system
+wide privileged driver (the "system" instance), and per-user unprivileged
+drivers (the "session" instance). A connection to the secret driver is
+automatically available when opening a connection to one of the stateful primary
+hypervisor drivers. It is none the less also possible to explicitly open just
+the secret driver, using the URI protocol "secret" Some example connection
URIs
+for the driver are:
+
+::
+
+ secret:///session (local access to per-user instance)
+ secret+unix:///session (local access to per-user instance)
+
+ secret:///system (local access to system instance)
+ secret+unix:///system (local access to system instance)
+ secret://example.com/system (remote access, TLS/x509)
+ secret+tcp://example.com/system (remote access, SASl/Kerberos)
+ secret+ssh://root@example.com/system (remote access, SSH tunnelled)
+
+Embedded driver
+~~~~~~~~~~~~~~~
+
+Since 6.1.0 the secret driver has experimental support for operating in an
+embedded mode. In this scenario, rather than connecting to the libvirtd daemon,
+the secret driver runs in the client application process directly. 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.
+
+::
+
+ secret:///embed?root=/some/dir
+
+Under the specified root directory the following locations will be used
+
+::
+
+ /some/dir
+ |
+ +- etc
+ | |
+ | +- secrets
+ |
+ +- run
+ |
+ +- secrets
+
+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.
+
+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. Normal practice
+would be to open the secret driver in embedded mode any time one of the other
+drivers is opened in embedded mode so that the two drivers can interact
+in-process.
diff --git a/docs/meson.build b/docs/meson.build
index d936091091..8499b3d595 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvsecret',
'drvtest',
'drvvbox',
'drvvirtuozzo',
@@ -81,6 +80,7 @@ docs_rst_files = [
'drvnodedev',
'drvopenvz',
'drvqemu',
+ 'drvsecret',
'errors',
'formatbackup',
'formatcheckpoint',
--
2.35.1
7:10 a.m.
New subject: [PATCH 10/29] docs: Convert 'drvtest' page to rST
The first sentence was moved up a paragraph to stop treating the first
sub-heading as a page subtitle.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvtest.html.in | 27 ---------------------------
docs/drvtest.rst | 21 +++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 22 insertions(+), 28 deletions(-)
delete mode 100644 docs/drvtest.html.in
create mode 100644 docs/drvtest.rst
diff --git a/docs/drvtest.html.in b/docs/drvtest.html.in
deleted file mode 100644
index 6884184e6f..0000000000
--- a/docs/drvtest.html.in
+++ /dev/null
@@ -1,27 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Test "mock" driver</h1>
-
- <h2>Connections to Test driver</h2>
-
- <p>
- The libvirt Test driver is a per-process fake hypervisor driver,
- with a driver name of 'test'. The driver maintains all its state
- in memory. It can start with a pre-configured default config, or
- be given a path to an alternate config. Some example connection URIs
- for the libvirt driver are:
- </p>
-
-<pre>
-test:///default (local access, default config)
-test:///path/to/driver/config.xml (local access, custom config)
-test+unix:///default (local access, default config, via daemon)
-test://example.com/default (remote access, TLS/x509)
-test+tcp://example.com/default (remote access, SASl/Kerberos)
-test+ssh://root@example.com/default (remote access, SSH tunnelled)
-</pre>
-
- </body>
-</html>
diff --git a/docs/drvtest.rst b/docs/drvtest.rst
new file mode 100644
index 0000000000..99578a47ba
--- /dev/null
+++ b/docs/drvtest.rst
@@ -0,0 +1,21 @@
+==================
+Test "mock" driver
+==================
+
+The libvirt ``test`` driver is a per-process fake hypervisor driver.
+
+Connections to Test driver
+--------------------------
+
+The driver maintains all its state in memory. It can start with
+a pre-configured default config, or be given a path to an alternate config. Some
+example connection URIs for the libvirt driver are:
+
+::
+
+ test:///default (local access, default config)
+ test:///path/to/driver/config.xml (local access, custom config)
+ test+unix:///default (local access, default config, via daemon)
+ test://example.com/default (remote access, TLS/x509)
+ test+tcp://example.com/default (remote access, SASl/Kerberos)
+ test+ssh://root@example.com/default (remote access, SSH tunnelled)
diff --git a/docs/meson.build b/docs/meson.build
index 8499b3d595..5995b2ec91 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvtest',
'drvvbox',
'drvvirtuozzo',
'drvvmware',
@@ -81,6 +80,7 @@ docs_rst_files = [
'drvopenvz',
'drvqemu',
'drvsecret',
+ 'drvtest',
'errors',
'formatbackup',
'formatcheckpoint',
--
2.35.1
7:59 a.m.
New subject: [PATCH 10/29] docs: Convert 'drvtest' page to rST
On Mon, Mar 28, 2022 at 02:10:25PM +0200, Peter Krempa wrote:
The first sentence was moved up a paragraph to stop treating the
first
sub-heading as a page subtitle.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 a.m.
New subject: [PATCH 11/29] docs: Convert 'drvvbox' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvvbox.html.in | 172 -------------------------------------------
docs/drvvbox.rst | 161 ++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 162 insertions(+), 173 deletions(-)
delete mode 100644 docs/drvvbox.html.in
create mode 100644 docs/drvvbox.rst
diff --git a/docs/drvvbox.html.in b/docs/drvvbox.html.in
deleted file mode 100644
index 0c0d14fa6a..0000000000
--- a/docs/drvvbox.html.in
+++ /dev/null
@@ -1,172 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>VirtualBox hypervisor driver</h1>
- <p>
- The libvirt VirtualBox driver can manage any VirtualBox version
- from version 4.0 onwards
- (<span class="since">since libvirt 3.0.0</span>).
- </p>
-
- <h2><a id="project">Project Links</a></h2>
-
- <ul>
- <li>
- The <a href="https://www.virtualbox.org/">VirtualBox</a>
- hypervisor
- </li>
- </ul>
-
- <h2>Connections to VirtualBox driver</h2>
-
- <p>
- The libvirt VirtualBox driver provides per-user drivers (the "session"
instance).
- The uri of the driver protocol is "vbox". Some example connection URIs for
the driver are:
- </p>
-
-<pre>
-vbox:///session (local access to per-user instance)
-vbox+unix:///session (local access to per-user instance)
-vbox+tcp://user@example.com/session (remote access, SASl/Kerberos)
-vbox+ssh://user@example.com/session (remote access, SSH tunnelled)
-</pre>
-
- <p>
- <strong>NOTE: as of libvirt 1.0.6, the VirtualBox driver will always
- run inside the libvirtd daemon, instead of being built-in to the
- libvirt.so library directly. This change was required due to the
- fact that VirtualBox code is LGPLv2-only licensed, which is not
- compatible with the libvirt.so license of LGPLv2-or-later. The
- daemon will be auto-started when the first connection to VirtualBox
- is requested. This change also means that it will not be possible
- to use VirtualBox URIs on the Windows platform, until additional
- work is completed to get the libvirtd daemon working there.</strong>
- </p>
-
- <h2><a id="xmlconfig">Example domain XML
config</a></h2>
-
-<pre>
-<domain type='vbox'>
- <name>vbox</name>
- <uuid>4dab22b31d52d8f32516782e98ab3fa0</uuid>
-
- <os>
- <type>hvm</type>
- <boot dev='cdrom'/>
- <boot dev='hd'/>
- <boot dev='fd'/>
- <boot dev='network'/>
- </os>
-
- <memory>654321</memory>
- <vcpu>1</vcpu>
-
- <features>
- <pae/>
- <acpi/>
- <apic/>
- </features>
-
- <devices>
- <!--Set IDE controller model to PIIX4 (default PIIX3)-->
- <controller type='ide' model='piix4'/>
-
- <controller type='scsi' index='0'/>
-
- <!--VirtualBox SAS Controller-->
- <controller type='scsi' index='1'
model='lsisas1068'/>
-
- <disk type='file' device='cdrom'>
- <source file='/home/user/Downloads/slax-6.0.9.iso'/>
- <target dev='hdc'/>
- <readonly/>
- </disk>
-
- <disk type='file' device='disk'>
- <source file='/home/user/tmp/vbox.vdi'/>
- <target dev='hdd'/>
- </disk>
-
- <!--Attach to the SCSI controller (index=0, default)-->
- <disk type='file' device='disk'>
- <source file='/home/user/tmp/vbox2.vdi'/>
- <target dev='sda' bus='scsi'/>
- </disk>
-
- <!--Attach to the SAS controller (index=1)-->
- <disk type='file' device='disk'>
- <source file='/home/user/tmp/vbox3.vdi'/>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='1' bus='0'
target='0' unit='0'/>
- </disk>
-
- <disk type='file' device='floppy'>
- <source file='/home/user/tmp/WIN98C.IMG'/>
- <target dev='fda'/>
- </disk>
-
- <filesystem type='mount'>
- <source dir='/home/user/stuff'/>
- <target dir='my-shared-folder'/>
- </filesystem>
-
- <!--BRIDGE-->
- <interface type='bridge'>
- <source bridge='eth0'/>
- <mac address='00:16:3e:5d:c7:9e'/>
- <model type='am79c973'/>
- </interface>
-
- <!--NAT-->
- <interface type='user'>
- <mac address='56:16:3e:5d:c7:9e'/>
- <model type='82540eM'/>
- </interface>
-
- <graphics type='desktop'/>
-
- <!--Activate the VRDE server with a port in 3389-3689 range-->
- <graphics type='rdp' autoport='yes'
multiUser='yes'/>
-
- <sound model='sb16'/>
-
- <parallel type='dev'>
- <source path='/dev/pts/1'/>
- <target port='0'/>
- </parallel>
-
- <parallel type='dev'>
- <source path='/dev/pts/2'/>
- <target port='1'/>
- </parallel>
-
- <serial type="dev">
- <source path="/dev/ttyS0"/>
- <target port="0"/>
- </serial>
-
- <serial type="pipe">
- <source path="/tmp/serial.txt"/>
- <target port="1"/>
- </serial>
-
- <hostdev mode='subsystem' type='usb'>
- <source>
- <vendor id='0x1234'/>
- <product id='0xbeef'/>
- </source>
- </hostdev>
-
- <hostdev mode='subsystem' type='usb'>
- <source>
- <vendor id='0x4321'/>
- <product id='0xfeeb'/>
- </source>
- </hostdev>
- </devices>
-</domain>
-</pre>
-
- </body>
-</html>
diff --git a/docs/drvvbox.rst b/docs/drvvbox.rst
new file mode 100644
index 0000000000..5154280ca2
--- /dev/null
+++ b/docs/drvvbox.rst
@@ -0,0 +1,161 @@
+.. role:: since
+
+============================
+VirtualBox hypervisor driver
+============================
+
+The libvirt VirtualBox driver can manage any VirtualBox version from version 4.0
+onwards ( :since:`since libvirt 3.0.0` ).
+
+Project Links
+-------------
+
+- The `VirtualBox <https://www.virtualbox.org/>`__ hypervisor
+
+Connections to VirtualBox driver
+--------------------------------
+
+The libvirt VirtualBox driver provides per-user drivers (the "session"
+instance). The uri of the driver protocol is "vbox". Some example connection
+URIs for the driver are:
+
+::
+
+ vbox:///session (local access to per-user instance)
+ vbox+unix:///session (local access to per-user instance)
+ vbox+tcp://user@example.com/session (remote access, SASl/Kerberos)
+ vbox+ssh://user@example.com/session (remote access, SSH tunnelled)
+
+**NOTE: as of libvirt 1.0.6, the VirtualBox driver will always run inside the
+libvirtd daemon, instead of being built-in to the libvirt.so library directly.
+This change was required due to the fact that VirtualBox code is LGPLv2-only
+licensed, which is not compatible with the libvirt.so license of
+LGPLv2-or-later. The daemon will be auto-started when the first connection to
+VirtualBox is requested. This change also means that it will not be possible to
+use VirtualBox URIs on the Windows platform, until additional work is completed
+to get the libvirtd daemon working there.**
+
+Example domain XML config
+-------------------------
+
+::
+
+ <domain type='vbox'>
+ <name>vbox</name>
+ <uuid>4dab22b31d52d8f32516782e98ab3fa0</uuid>
+
+ <os>
+ <type>hvm</type>
+ <boot dev='cdrom'/>
+ <boot dev='hd'/>
+ <boot dev='fd'/>
+ <boot dev='network'/>
+ </os>
+
+ <memory>654321</memory>
+ <vcpu>1</vcpu>
+
+ <features>
+ <pae/>
+ <acpi/>
+ <apic/>
+ </features>
+
+ <devices>
+ <!--Set IDE controller model to PIIX4 (default PIIX3)-->
+ <controller type='ide' model='piix4'/>
+
+ <controller type='scsi' index='0'/>
+
+ <!--VirtualBox SAS Controller-->
+ <controller type='scsi' index='1'
model='lsisas1068'/>
+
+ <disk type='file' device='cdrom'>
+ <source file='/home/user/Downloads/slax-6.0.9.iso'/>
+ <target dev='hdc'/>
+ <readonly/>
+ </disk>
+
+ <disk type='file' device='disk'>
+ <source file='/home/user/tmp/vbox.vdi'/>
+ <target dev='hdd'/>
+ </disk>
+
+ <!--Attach to the SCSI controller (index=0, default)-->
+ <disk type='file' device='disk'>
+ <source file='/home/user/tmp/vbox2.vdi'/>
+ <target dev='sda' bus='scsi'/>
+ </disk>
+
+ <!--Attach to the SAS controller (index=1)-->
+ <disk type='file' device='disk'>
+ <source file='/home/user/tmp/vbox3.vdi'/>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='1' bus='0'
target='0' unit='0'/>
+ </disk>
+
+ <disk type='file' device='floppy'>
+ <source file='/home/user/tmp/WIN98C.IMG'/>
+ <target dev='fda'/>
+ </disk>
+
+ <filesystem type='mount'>
+ <source dir='/home/user/stuff'/>
+ <target dir='my-shared-folder'/>
+ </filesystem>
+
+ <!--BRIDGE-->
+ <interface type='bridge'>
+ <source bridge='eth0'/>
+ <mac address='00:16:3e:5d:c7:9e'/>
+ <model type='am79c973'/>
+ </interface>
+
+ <!--NAT-->
+ <interface type='user'>
+ <mac address='56:16:3e:5d:c7:9e'/>
+ <model type='82540eM'/>
+ </interface>
+
+ <graphics type='desktop'/>
+
+ <!--Activate the VRDE server with a port in 3389-3689 range-->
+ <graphics type='rdp' autoport='yes'
multiUser='yes'/>
+
+ <sound model='sb16'/>
+
+ <parallel type='dev'>
+ <source path='/dev/pts/1'/>
+ <target port='0'/>
+ </parallel>
+
+ <parallel type='dev'>
+ <source path='/dev/pts/2'/>
+ <target port='1'/>
+ </parallel>
+
+ <serial type="dev">
+ <source path="/dev/ttyS0"/>
+ <target port="0"/>
+ </serial>
+
+ <serial type="pipe">
+ <source path="/tmp/serial.txt"/>
+ <target port="1"/>
+ </serial>
+
+ <hostdev mode='subsystem' type='usb'>
+ <source>
+ <vendor id='0x1234'/>
+ <product id='0xbeef'/>
+ </source>
+ </hostdev>
+
+ <hostdev mode='subsystem' type='usb'>
+ <source>
+ <vendor id='0x4321'/>
+ <product id='0xfeeb'/>
+ </source>
+ </hostdev>
+ </devices>
+ </domain>
diff --git a/docs/meson.build b/docs/meson.build
index 5995b2ec91..954c4e4b96 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvvbox',
'drvvirtuozzo',
'drvvmware',
'drvxen',
@@ -81,6 +80,7 @@ docs_rst_files = [
'drvqemu',
'drvsecret',
'drvtest',
+ 'drvvbox',
'errors',
'formatbackup',
'formatcheckpoint',
--
2.35.1
7:10 a.m.
New subject: [PATCH 12/29] docs: Convert 'drvvirtuozzo' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvvirtuozzo.html.in | 70 ---------------------------------------
docs/drvvirtuozzo.rst | 60 +++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 61 insertions(+), 71 deletions(-)
delete mode 100644 docs/drvvirtuozzo.html.in
create mode 100644 docs/drvvirtuozzo.rst
diff --git a/docs/drvvirtuozzo.html.in b/docs/drvvirtuozzo.html.in
deleted file mode 100644
index e47f72bad1..0000000000
--- a/docs/drvvirtuozzo.html.in
+++ /dev/null
@@ -1,70 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Virtuozzo driver</h1>
- <ul id="toc"></ul>
- <p>
- The libvirt vz driver can manage Virtuozzo starting from version 6.0.
- </p>
-
-
- <h2><a id="project">Project Links</a></h2>
- <ul>
- <li>
- The <a href="https://www.virtuozzo.com/">Virtuozzo</a>
Solution.
- </li>
- </ul>
-
-
- <h2><a id="uri">Connections to the Virtuozzo
driver</a></h2>
- <p>
- The libvirt Virtuozzo driver is a single-instance privileged driver, with a
driver name of 'virtuozzo'. Some example connection URIs for the libvirt driver
are:
- </p>
-<pre>
-vz:///system (local access)
-vz+unix:///system (local access)
-vz://example.com/system (remote access, TLS/x509)
-vz+tcp://example.com/system (remote access, SASl/Kerberos)
-vz+ssh://root@example.com/system (remote access, SSH tunnelled)
-</pre>
-
- <h2><a id="example">Example guest domain XML
configuration</a></h2>
-
- <p>
- Virtuozzo driver require at least one hard disk for new domains
- at this time. It is used for defining directory, where VM should
- be created.
- </p>
-
-<pre>
-<domain type='vz'>
- <name>demo</name>
- <uuid>54cdecad-4492-4e31-a209-33cc21d64057</uuid>
- <description>some description</description>
- <memory unit='KiB'>1048576</memory>
- <currentMemory unit='KiB'>1048576</currentMemory>
- <vcpu placement='static'>2</vcpu>
- <os>
- <type arch='x86_64'>hvm</type>
- </os>
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>destroy</on_reboot>
- <on_crash>destroy</on_crash>
- <devices>
- <disk type='file' device='disk'>
- <source file='/storage/vol1'/>
- <target dev='hda'/>
- </disk>
- <video>
- <model type='vga' vram='33554432' heads='1'>
- <acceleration accel3d='no' accel2d='no'/>
- </model>
- </video>
- </devices>
-</domain>
-
-</pre>
-
-</body></html>
diff --git a/docs/drvvirtuozzo.rst b/docs/drvvirtuozzo.rst
new file mode 100644
index 0000000000..fbb6ab0e71
--- /dev/null
+++ b/docs/drvvirtuozzo.rst
@@ -0,0 +1,60 @@
+================
+Virtuozzo driver
+================
+
+The libvirt vz driver can manage Virtuozzo starting from version 6.0.
+
+Project Links
+-------------
+
+- The `Virtuozzo <https://www.virtuozzo.com/>`__ Solution.
+
+Connections to the Virtuozzo driver
+-----------------------------------
+
+The libvirt Virtuozzo driver is a single-instance privileged driver, with a
+driver name of 'virtuozzo'. Some example connection URIs for the libvirt driver
+are:
+
+::
+
+ vz:///system (local access)
+ vz+unix:///system (local access)
+ vz://example.com/system (remote access, TLS/x509)
+ vz+tcp://example.com/system (remote access, SASl/Kerberos)
+ vz+ssh://root@example.com/system (remote access, SSH tunnelled)
+
+Example guest domain XML configuration
+--------------------------------------
+
+Virtuozzo driver require at least one hard disk for new domains at this time. It
+is used for defining directory, where VM should be created.
+
+::
+
+ <domain type='vz'>
+ <name>demo</name>
+ <uuid>54cdecad-4492-4e31-a209-33cc21d64057</uuid>
+ <description>some description</description>
+ <memory unit='KiB'>1048576</memory>
+ <currentMemory unit='KiB'>1048576</currentMemory>
+ <vcpu placement='static'>2</vcpu>
+ <os>
+ <type arch='x86_64'>hvm</type>
+ </os>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>destroy</on_reboot>
+ <on_crash>destroy</on_crash>
+ <devices>
+ <disk type='file' device='disk'>
+ <source file='/storage/vol1'/>
+ <target dev='hda'/>
+ </disk>
+ <video>
+ <model type='vga' vram='33554432' heads='1'>
+ <acceleration accel3d='no' accel2d='no'/>
+ </model>
+ </video>
+ </devices>
+ </domain>
diff --git a/docs/meson.build b/docs/meson.build
index 954c4e4b96..99732f57ba 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvvirtuozzo',
'drvvmware',
'drvxen',
'firewall',
@@ -81,6 +80,7 @@ docs_rst_files = [
'drvsecret',
'drvtest',
'drvvbox',
+ 'drvvirtuozzo',
'errors',
'formatbackup',
'formatcheckpoint',
--
2.35.1
7:10 a.m.
New subject: [PATCH 13/29] docs: Convert 'drvvmware' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvvmware.html.in | 89 ------------------------------------------
docs/drvvmware.rst | 72 ++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 73 insertions(+), 90 deletions(-)
delete mode 100644 docs/drvvmware.html.in
create mode 100644 docs/drvvmware.rst
diff --git a/docs/drvvmware.html.in b/docs/drvvmware.html.in
deleted file mode 100644
index d581ad1d1c..0000000000
--- a/docs/drvvmware.html.in
+++ /dev/null
@@ -1,89 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>VMware Workstation / Player / Fusion hypervisors driver</h1>
- <p>
- The libvirt VMware driver should be able to manage any Workstation,
- Player, Fusion version supported by the VMware VIX API. See the
- compatibility list
- <a
href="https://www.vmware.com/support/developer/vix-api/vix110_refere...;.
- </p>
- <p>
- This driver uses the "vmrun" utility which is distributed with the VMware
VIX API.
- You can download the VIX API
- from <a
href="https://www.vmware.com/support/developer/vix-api/">her...;.
- </p>
-
- <h2><a id="project">Project Links</a></h2>
-
- <ul>
- <li>
- The <a href="https://www.vmware.com/">VMware Workstation and
- Player</a> hypervisors
- </li>
- <li>
- The <a href="https://www.vmware.com/fusion">VMware
Fusion</a>
- hypervisor
- </li>
- </ul>
-
- <h2>Connections to VMware driver</h2>
-
- <p>
- The libvirt VMware driver provides per-user drivers (the "session"
instance).
- Three uris are available:
- </p>
- <ul>
- <li>"vmwareplayer" for VMware Player</li>
- <li>"vmwarews" for VMware Workstation</li>
- <li>"vmwarefusion" for VMware Fusion</li>
- </ul>
- <p>
- Some example connection URIs for the driver are:
- </p>
-
-<pre>
-vmwareplayer:///session (local access to VMware Player per-user
instance)
-vmwarews:///session (local access to VMware Workstation per-user
instance)
-vmwarefusion:///session (local access to VMware Fusion per-user
instance)
-vmwarews+tcp://user@example.com/session (remote access to VMware Workstation,
SASl/Kerberos)
-vmwarews+ssh://user@example.com/session (remote access to VMware Workstation, SSH
tunnelled)
-</pre>
-
- <h2><a id="xmlconfig">Example domain XML
config</a></h2>
-
-<pre>
-<domain type='vmware'>
- <name>vmware</name>
- <uuid>bea92244-8885-4562-828b-3b086731c5b1</uuid>
-
- <os>
- <type>hvm</type>
- </os>
-
- <memory>524288</memory>
- <vcpu>1</vcpu>
-
- <features>
- <pae/>
- <acpi/>
- </features>
-
- <devices>
- <disk type='file' device='disk'>
- <source file='/home/user/tmp/disk.vmdk'/>
- <target bus='ide' dev='hda'/>
- </disk>
-
- <interface type='bridge'>
- <target dev='/dev/vmnet1'/>
- <source bridge=''/>
- <mac address='00:16:3e:5d:c7:9e'/>
- </interface>
- </devices>
-</domain>
-</pre>
-
- </body>
-</html>
diff --git a/docs/drvvmware.rst b/docs/drvvmware.rst
new file mode 100644
index 0000000000..6db1a78a17
--- /dev/null
+++ b/docs/drvvmware.rst
@@ -0,0 +1,72 @@
+=======================================================
+VMware Workstation / Player / Fusion hypervisors driver
+=======================================================
+
+The libvirt VMware driver should be able to manage any Workstation, Player,
+Fusion version supported by the VMware VIX API. See the compatibility list
+`here <https://www.vmware.com/support/developer/vix-api/vix110_reference/>`__.
+
+This driver uses the "vmrun" utility which is distributed with the VMware VIX
+API. You can download the VIX API from
+`here <https://www.vmware.com/support/developer/vix-api/>`__.
+
+Project Links
+-------------
+
+- The `VMware Workstation and Player <https://www.vmware.com/>`__ hypervisors
+- The `VMware Fusion <https://www.vmware.com/fusion>`__ hypervisor
+
+Connections to VMware driver
+----------------------------
+
+The libvirt VMware driver provides per-user drivers (the "session" instance).
+Three uris are available:
+
+- "vmwareplayer" for VMware Player
+- "vmwarews" for VMware Workstation
+- "vmwarefusion" for VMware Fusion
+
+Some example connection URIs for the driver are:
+
+::
+
+ vmwareplayer:///session (local access to VMware Player per-user
instance)
+ vmwarews:///session (local access to VMware Workstation per-user
instance)
+ vmwarefusion:///session (local access to VMware Fusion per-user
instance)
+ vmwarews+tcp://user@example.com/session (remote access to VMware Workstation,
SASl/Kerberos)
+ vmwarews+ssh://user@example.com/session (remote access to VMware Workstation, SSH
tunnelled)
+
+Example domain XML config
+-------------------------
+
+::
+
+ <domain type='vmware'>
+ <name>vmware</name>
+ <uuid>bea92244-8885-4562-828b-3b086731c5b1</uuid>
+
+ <os>
+ <type>hvm</type>
+ </os>
+
+ <memory>524288</memory>
+ <vcpu>1</vcpu>
+
+ <features>
+ <pae/>
+ <acpi/>
+ </features>
+
+ <devices>
+ <disk type='file' device='disk'>
+ <source file='/home/user/tmp/disk.vmdk'/>
+ <target bus='ide' dev='hda'/>
+ </disk>
+
+ <interface type='bridge'>
+ <target dev='/dev/vmnet1'/>
+ <source bridge=''/>
+ <mac address='00:16:3e:5d:c7:9e'/>
+ </interface>
+ </devices>
+ </domain>
diff --git a/docs/meson.build b/docs/meson.build
index 99732f57ba..940fbedcfa 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvvmware',
'drvxen',
'firewall',
'format',
@@ -81,6 +80,7 @@ docs_rst_files = [
'drvtest',
'drvvbox',
'drvvirtuozzo',
+ 'drvvmware',
'errors',
'formatbackup',
'formatcheckpoint',
--
2.35.1
7:10 a.m.
New subject: [PATCH 14/29] docs: Convert 'drvxen' page to rST
Fix the referenced anchor in 'formatdomain.rst' right away.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvxen.html.in | 358 ------------------------------------------
docs/drvxen.rst | 338 +++++++++++++++++++++++++++++++++++++++
docs/formatdomain.rst | 2 +-
docs/meson.build | 2 +-
4 files changed, 340 insertions(+), 360 deletions(-)
delete mode 100644 docs/drvxen.html.in
create mode 100644 docs/drvxen.rst
diff --git a/docs/drvxen.html.in b/docs/drvxen.html.in
deleted file mode 100644
index 95be36c879..0000000000
--- a/docs/drvxen.html.in
+++ /dev/null
@@ -1,358 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>libxl hypervisor driver for Xen</h1>
-
- <ul id="toc"></ul>
-
- <p>
- The libvirt libxl driver provides the ability to manage virtual
- machines on any Xen release from 4.6.0 onwards.
- </p>
-
- <h2><a id="project">Project Links</a></h2>
-
- <ul>
- <li>
- The <a href="https://www.xenproject.org">Xen</a>
- hypervisor on Linux and Solaris hosts
- </li>
- </ul>
-
- <h2><a id="prereq">Deployment
pre-requisites</a></h2>
-
- <p>
- The libvirt libxl driver uses Xen's libxl API, also known as
- libxenlight, to implement libvirt's hypervisor driver
- functionality. libxl provides a consolidated interface for
- managing a Xen host and its virtual machines, unlike old
- versions of Xen where applications often had to communicate
- with xend, xenstored, and the hypervisor itself via hypercalls.
- With libxl the only pre-requisit is a properly installed Xen
- host with the libxl toolstack running in a service domain
- (often Domain-0).
- </p>
-
- <h2><a id="uri">Connections to libxl
driver</a></h2>
-
- <p>
- The libvirt libxl driver is a single-instance privileged driver,
- with a driver name of 'xen'. Some example connection URIs for
- the libxl driver are:
- </p>
-
-<pre>
-xen:///system (local access, direct)
-xen+unix:///system (local access, via daemon)
-xen://example.com/system (remote access, TLS/x509)
-xen+tcp://example.com/system (remote access, SASl/Kerberos)
-xen+ssh://root@example.com/system (remote access, SSH tunnelled)
-</pre>
-
-
- <h2><a id="configFiles">Location of configuration
files</a></h2>
-
- <p>
- The libxl driver comes with sane default values. However, during its
- initialization it reads a configuration file which offers system
- administrator to override some of that default. The file is located
- under <code>/etc/libvirt/libxl.conf</code>
- </p>
-
-
- <h2><a id="imex">Import and export of libvirt domain XML
configs</a></h2>
-
- <p>
- The libxl driver currently supports three native
- config formats. The first, known as <code>xen-xm</code>, is the
- original Xen virtual machine config format used by the legacy
- xm/xend toolstack. The second, known as <code>xen-sxpr</code>,
- is also one of the original formats that was used by xend's
- legacy HTTP RPC service (<span class='removed'>removed in
5.6.0</span>)
- </p>
-
- <p>
- The third format is <code>xen-xl</code>, which is the virtual
- machine config format supported by modern Xen. The <code>xen-xl</code>
- format is described in the xl.cfg(5) man page.
- </p>
-
- <h3><a id="xmlimport">Converting from XM config files to domain
XML</a></h3>
-
- <p>
- The <code>virsh domxml-from-native</code> provides a way to convert an
- existing set of xl, xm, or sxpr config files to libvirt Domain XML,
- which can then be used by libvirt.
- </p>
-
- <pre>$ virsh -c xen:///system domxml-from-native xen-xm rhel5.cfg
-<domain type='xen'>
- <name>rhel5pv</name>
- <uuid>8f07fe28-753f-2729-d76d-bdbd892f949a</uuid>
- <memory>2560000</memory>
- <currentMemory>307200</currentMemory>
- <vcpu>4</vcpu>
- <bootloader>/usr/bin/pygrub</bootloader>
- <os>
- <type arch='x86_64'
machine='xenpv'>linux</type>
- </os>
- <clock offset='utc'/>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>restart</on_crash>
- <devices>
- <disk type='file' device='disk'>
- <driver name='tap' type='aio'/>
- <source file='/var/lib/xen/images/rhel5pv.img'/>
- <target dev='xvda' bus='xen'/>
- </disk>
- <disk type='file' device='disk'>
- <driver name='tap' type='qcow'/>
- <source file='/root/qcow1-xen.img'/>
- <target dev='xvdd' bus='xen'/>
- </disk>
- <interface type='bridge'>
- <mac address='00:16:3e:60:36:ba'/>
- <source bridge='xenbr0'/>
- </interface>
- <console type='pty'>
- <target port='0'/>
- </console>
- <input type='mouse' bus='xen'/>
- <graphics type='vnc' port='-1' autoport='yes'
listen='0.0.0.0'/>
- </devices>
-</domain></pre>
-
- <h3><a id="xmlexport">Converting from domain XML to XM config
files</a></h3>
-
- <p>
- The <code>virsh domxml-to-native</code> provides a way to convert a
- guest description using libvirt Domain XML into xl, xm, or sxpr config
- format.
- </p>
-
- <pre>$ virsh -c xen:///system domxml-to-native xen-xm rhel5pv.xml
-name = "rhel5pv"
-uuid = "8f07fe28-753f-2729-d76d-bdbd892f949a"
-maxmem = 2500
-memory = 300
-vcpus = 4
-bootloader = "/usr/bin/pygrub"
-kernel = "/var/lib/xen/boot_kernel.0YK-cS"
-ramdisk = "/var/lib/xen/boot_ramdisk.vWgrxK"
-extra = "ro root=/dev/VolGroup00/LogVol00 rhgb quiet"
-on_poweroff = "destroy"
-on_reboot = "restart"
-on_crash = "restart"
-sdl = 0
-vnc = 1
-vncunused = 1
-vnclisten = "0.0.0.0"
-disk = [ "tap:aio:/var/lib/xen/images/rhel5pv.img,xvda,w",
"tap:qcow:/root/qcow1-xen.img,xvdd,w" ]
-vif = [ "mac=00:16:3e:60:36:ba,bridge=virbr0,script=vif-bridge,vifname=vif5.0"
]</pre>
-
- <h2><a id="xencommand">Pass-through of arbitrary command-line
arguments
- to the qemu device model</a></h2>
-
- <p><span class="since">Since 6.7.0</span>, the Xen driver
supports passing
- arbitrary command-line arguments to the qemu device model used by Xen with
- the <code><xen:commandline></code> element under
<code>domain</code>.
- In order to use command-line pass-through, an XML namespace request must be
- issued that pulls in
<code>http://libvirt.org/schemas/domain/xen/1.0</code>;.
- With the namespace in place, it is then possible to add
- <code><xen:arg></code>sub-elements to
- <code><xen:commandline></code> describing each argument
passed to
- the device model when starting the domain.
- </p>
- <p>The following example illustrates passing arguments to the QEMU device
- model that define a floppy drive, which Xen does not support through its
- public APIs:
- </p>
- <pre>
-<domain type="xen"
xmlns:xen="http://libvirt.org/schemas/domain/xen/1.0">
- ...
- <xen:commandline>
- <xen:arg value='-drive'/>
- <xen:arg
value='file=/path/to/image,format=raw,if=none,id=drive-fdc0-0-0'/>
- <xen:arg value='-global'/>
- <xen:arg value='isa-fdc.driveA=drive-fdc0-0-0'/>
- </xen:commandline>
-</domain>
- </pre>
-
- <h2><a id="xmlconfig">Example domain XML
config</a></h2>
-
- <p>
- Below are some example XML configurations for Xen guest domains.
- For full details of the available options, consult the <a
href="formatdomain.html">domain XML format</a>
- guide.
- </p>
-
- <h3>Paravirtualized guest bootloader</h3>
-
- <p>
- Using a bootloader allows a paravirtualized guest to be booted using
- a kernel stored inside its virtual disk image
- </p>
-
- <pre><domain type='xen' >
- <name>fc8</name>
- <bootloader>/usr/bin/pygrub</bootloader>
- <os>
- <type>linux</type>
- </os>
- <memory>131072</memory>
- <vcpu>1</vcpu>
- <devices>
- <disk type='file'>
- <source file='/var/lib/xen/images/fc4.img'/>
- <target dev='sda1'/>
- </disk>
- <interface type='bridge'>
- <source bridge='xenbr0'/>
- <mac address='aa:00:00:00:00:11'/>
- <script path='/etc/xen/scripts/vif-bridge'/>
- </interface>
- <console tty='/dev/pts/5'/>
- </devices>
-</domain></pre>
-
- <h3>Paravirtualized guest direct kernel boot</h3>
-
- <p>
- For installation of paravirtualized guests it is typical to boot the
- domain using a kernel and initrd stored in the host OS
- </p>
-
- <pre><domain type='xen' >
- <name>fc8</name>
- <os>
- <type>linux</type>
-
<kernel>/var/lib/xen/install/vmlinuz-fedora8-x86_64</kernel>
-
<initrd>/var/lib/xen/install/initrd-vmlinuz-fedora8-x86_64</initrd>
- <cmdline> kickstart=http://example.com/myguest.ks
</cmdline>
- </os>
- <memory>131072</memory>
- <vcpu>1</vcpu>
- <devices>
- <disk type='file'>
- <source file='/var/lib/xen/images/fc4.img'/>
- <target dev='sda1'/>
- </disk>
- <interface type='bridge'>
- <source bridge='xenbr0'/>
- <mac address='aa:00:00:00:00:11'/>
- <script path='/etc/xen/scripts/vif-bridge'/>
- </interface>
- <graphics type='vnc' port='-1'/>
- <console tty='/dev/pts/5'/>
- </devices>
-</domain></pre>
-
- <h3>Fullyvirtualized guest BIOS boot</h3>
-
- <p>
- Fullyvirtualized guests use the emulated BIOS to boot off the primary
- harddisk, CDROM or Network PXE ROM.
- </p>
-
- <pre><domain type='xen' id='3'>
- <name>fv0</name>
- <uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
- <os>
- <type>hvm</type>
- <loader>/usr/lib/xen/boot/hvmloader</loader>
- <boot dev='hd'/>
- </os>
- <memory>524288</memory>
- <vcpu>1</vcpu>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>restart</on_crash>
- <features>
- <pae/>
- <acpi/>
- <apic/>
- </features>
- <clock sync="localtime"/>
- <devices>
- <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
- <interface type='bridge'>
- <source bridge='xenbr0'/>
- <mac address='00:16:3e:5d:c7:9e'/>
- <script path='vif-bridge'/>
- </interface>
- <disk type='file'>
- <source file='/var/lib/xen/images/fv0'/>
- <target dev='hda'/>
- </disk>
- <disk type='file' device='cdrom'>
- <source file='/var/lib/xen/images/fc5-x86_64-boot.iso'/>
- <target dev='hdc'/>
- <readonly/>
- </disk>
- <disk type='file' device='floppy'>
- <source file='/root/fd.img'/>
- <target dev='fda'/>
- </disk>
- <graphics type='vnc' port='5904'/>
- </devices>
-</domain></pre>
-
- <h3>Fullyvirtualized guest direct kernel boot</h3>
-
- <p>
- With Xen 3.2.0 or later it is possible to bypass the BIOS and directly
- boot a Linux kernel and initrd as a fullyvirtualized domain. This allows
- for complete automation of OS installation, for example using the Anaconda
- kickstart support.
- </p>
-
- <pre><domain type='xen' id='3'>
- <name>fv0</name>
- <uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
- <os>
- <type>hvm</type>
- <loader>/usr/lib/xen/boot/hvmloader</loader>
-
<kernel>/var/lib/xen/install/vmlinuz-fedora8-x86_64</kernel>
-
<initrd>/var/lib/xen/install/initrd-vmlinuz-fedora8-x86_64</initrd>
- <cmdline> kickstart=http://example.com/myguest.ks
</cmdline>
- </os>
- <memory>524288</memory>
- <vcpu>1</vcpu>
- <on_poweroff>destroy</on_poweroff>
- <on_reboot>restart</on_reboot>
- <on_crash>restart</on_crash>
- <features>
- <pae/>
- <acpi/>
- <apic/>
- </features>
- <clock sync="localtime"/>
- <devices>
- <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
- <interface type='bridge'>
- <source bridge='xenbr0'/>
- <mac address='00:16:3e:5d:c7:9e'/>
- <script path='vif-bridge'/>
- </interface>
- <disk type='file'>
- <source file='/var/lib/xen/images/fv0'/>
- <target dev='hda'/>
- </disk>
- <disk type='file' device='cdrom'>
- <source file='/var/lib/xen/images/fc5-x86_64-boot.iso'/>
- <target dev='hdc'/>
- <readonly/>
- </disk>
- <disk type='file' device='floppy'>
- <source file='/root/fd.img'/>
- <target dev='fda'/>
- </disk>
- <graphics type='vnc' port='5904'/>
- </devices>
-</domain></pre>
-
- </body>
-</html>
diff --git a/docs/drvxen.rst b/docs/drvxen.rst
new file mode 100644
index 0000000000..c131d52c7a
--- /dev/null
+++ b/docs/drvxen.rst
@@ -0,0 +1,338 @@
+.. role:: since
+
+===============================
+libxl hypervisor driver for Xen
+===============================
+
+.. contents::
+
+The libvirt libxl driver provides the ability to manage virtual machines on any
+Xen release from 4.6.0 onwards.
+
+Project Links
+-------------
+
+- The `Xen <https://www.xenproject.org>`__ hypervisor on Linux and Solaris
+ hosts
+
+Deployment pre-requisites
+-------------------------
+
+The libvirt libxl driver uses Xen's libxl API, also known as libxenlight, to
+implement libvirt's hypervisor driver functionality. libxl provides a
+consolidated interface for managing a Xen host and its virtual machines, unlike
+old versions of Xen where applications often had to communicate with xend,
+xenstored, and the hypervisor itself via hypercalls. With libxl the only
+pre-requisit is a properly installed Xen host with the libxl toolstack running
+in a service domain (often Domain-0).
+
+Connections to libxl driver
+---------------------------
+
+The libvirt libxl driver is a single-instance privileged driver, with a driver
+name of 'xen'. Some example connection URIs for the libxl driver are:
+
+::
+
+ xen:///system (local access, direct)
+ xen+unix:///system (local access, via daemon)
+ xen://example.com/system (remote access, TLS/x509)
+ xen+tcp://example.com/system (remote access, SASl/Kerberos)
+ xen+ssh://root@example.com/system (remote access, SSH tunnelled)
+
+Location of configuration files
+-------------------------------
+
+The libxl driver comes with sane default values. However, during its
+initialization it reads a configuration file which offers system administrator
+to override some of that default. The file is located under
+``/etc/libvirt/libxl.conf``
+
+Import and export of libvirt domain XML configs
+-----------------------------------------------
+
+The libxl driver currently supports three native config formats. The first,
+known as ``xen-xm``, is the original Xen virtual machine config format used by
+the legacy xm/xend toolstack. The second, known as ``xen-sxpr``, is also one of
+the original formats that was used by xend's legacy HTTP RPC service (
+:since:`removed in 5.6.0` )
+
+The third format is ``xen-xl``, which is the virtual machine config format
+supported by modern Xen. The ``xen-xl`` format is described in the xl.cfg(5) man
+page.
+
+Converting from XM config files to domain XML
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-from-native`` provides a way to convert an existing set of
+xl, xm, or sxpr config files to libvirt Domain XML, which can then be used by
+libvirt.
+
+::
+
+ $ virsh -c xen:///system domxml-from-native xen-xm rhel5.cfg
+ <domain type='xen'>
+ <name>rhel5pv</name>
+ <uuid>8f07fe28-753f-2729-d76d-bdbd892f949a</uuid>
+ <memory>2560000</memory>
+ <currentMemory>307200</currentMemory>
+ <vcpu>4</vcpu>
+ <bootloader>/usr/bin/pygrub</bootloader>
+ <os>
+ <type arch='x86_64' machine='xenpv'>linux</type>
+ </os>
+ <clock offset='utc'/>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>restart</on_crash>
+ <devices>
+ <disk type='file' device='disk'>
+ <driver name='tap' type='aio'/>
+ <source file='/var/lib/xen/images/rhel5pv.img'/>
+ <target dev='xvda' bus='xen'/>
+ </disk>
+ <disk type='file' device='disk'>
+ <driver name='tap' type='qcow'/>
+ <source file='/root/qcow1-xen.img'/>
+ <target dev='xvdd' bus='xen'/>
+ </disk>
+ <interface type='bridge'>
+ <mac address='00:16:3e:60:36:ba'/>
+ <source bridge='xenbr0'/>
+ </interface>
+ <console type='pty'>
+ <target port='0'/>
+ </console>
+ <input type='mouse' bus='xen'/>
+ <graphics type='vnc' port='-1' autoport='yes'
listen='0.0.0.0'/>
+ </devices>
+ </domain>
+
+Converting from domain XML to XM config files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``virsh domxml-to-native`` provides a way to convert a guest description
+using libvirt Domain XML into xl, xm, or sxpr config format.
+
+::
+
+ $ virsh -c xen:///system domxml-to-native xen-xm rhel5pv.xml
+ name = "rhel5pv"
+ uuid = "8f07fe28-753f-2729-d76d-bdbd892f949a"
+ maxmem = 2500
+ memory = 300
+ vcpus = 4
+ bootloader = "/usr/bin/pygrub"
+ kernel = "/var/lib/xen/boot_kernel.0YK-cS"
+ ramdisk = "/var/lib/xen/boot_ramdisk.vWgrxK"
+ extra = "ro root=/dev/VolGroup00/LogVol00 rhgb quiet"
+ on_poweroff = "destroy"
+ on_reboot = "restart"
+ on_crash = "restart"
+ sdl = 0
+ vnc = 1
+ vncunused = 1
+ vnclisten = "0.0.0.0"
+ disk = [ "tap:aio:/var/lib/xen/images/rhel5pv.img,xvda,w",
"tap:qcow:/root/qcow1-xen.img,xvdd,w" ]
+ vif = [
"mac=00:16:3e:60:36:ba,bridge=virbr0,script=vif-bridge,vifname=vif5.0" ]
+
+Pass-through of arbitrary command-line arguments to the qemu device model
+-------------------------------------------------------------------------
+
+:since:`Since 6.7.0` , the Xen driver supports passing arbitrary command-line
+arguments to the qemu device model used by Xen with the ``<xen:commandline>``
+element under ``domain``. In order to use command-line pass-through, an XML
+namespace request must be issued that pulls in
+``http://libvirt.org/schemas/domain/xen/1.0``. With the namespace in place, it
+is then possible to add ``<xen:arg>``\ sub-elements to ``<xen:commandline>``
+describing each argument passed to the device model when starting the domain.
+
+The following example illustrates passing arguments to the QEMU device model
+that define a floppy drive, which Xen does not support through its public APIs:
+
+::
+
+ <domain type="xen"
xmlns:xen="http://libvirt.org/schemas/domain/xen/1.0">
+ ...
+ <xen:commandline>
+ <xen:arg value='-drive'/>
+ <xen:arg
value='file=/path/to/image,format=raw,if=none,id=drive-fdc0-0-0'/>
+ <xen:arg value='-global'/>
+ <xen:arg value='isa-fdc.driveA=drive-fdc0-0-0'/>
+ </xen:commandline>
+ </domain>
+
+Example domain XML config
+-------------------------
+
+Below are some example XML configurations for Xen guest domains. For full
+details of the available options, consult the `domain XML
+format <formatdomain.html>`__ guide.
+
+Paravirtualized guest bootloader
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using a bootloader allows a paravirtualized guest to be booted using a kernel
+stored inside its virtual disk image
+
+::
+
+ <domain type='xen' >
+ <name>fc8</name>
+ <bootloader>/usr/bin/pygrub</bootloader>
+ <os>
+ <type>linux</type>
+ </os>
+ <memory>131072</memory>
+ <vcpu>1</vcpu>
+ <devices>
+ <disk type='file'>
+ <source file='/var/lib/xen/images/fc4.img'/>
+ <target dev='sda1'/>
+ </disk>
+ <interface type='bridge'>
+ <source bridge='xenbr0'/>
+ <mac address='aa:00:00:00:00:11'/>
+ <script path='/etc/xen/scripts/vif-bridge'/>
+ </interface>
+ <console tty='/dev/pts/5'/>
+ </devices>
+ </domain>
+
+Paravirtualized guest direct kernel boot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For installation of paravirtualized guests it is typical to boot the domain
+using a kernel and initrd stored in the host OS
+
+::
+
+ <domain type='xen' >
+ <name>fc8</name>
+ <os>
+ <type>linux</type>
+ <kernel>/var/lib/xen/install/vmlinuz-fedora8-x86_64</kernel>
+ <initrd>/var/lib/xen/install/initrd-vmlinuz-fedora8-x86_64</initrd>
+ <cmdline> kickstart=http://example.com/myguest.ks </cmdline>
+ </os>
+ <memory>131072</memory>
+ <vcpu>1</vcpu>
+ <devices>
+ <disk type='file'>
+ <source file='/var/lib/xen/images/fc4.img'/>
+ <target dev='sda1'/>
+ </disk>
+ <interface type='bridge'>
+ <source bridge='xenbr0'/>
+ <mac address='aa:00:00:00:00:11'/>
+ <script path='/etc/xen/scripts/vif-bridge'/>
+ </interface>
+ <graphics type='vnc' port='-1'/>
+ <console tty='/dev/pts/5'/>
+ </devices>
+ </domain>
+
+Fullyvirtualized guest BIOS boot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Fullyvirtualized guests use the emulated BIOS to boot off the primary harddisk,
+CDROM or Network PXE ROM.
+
+::
+
+ <domain type='xen' id='3'>
+ <name>fv0</name>
+ <uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
+ <os>
+ <type>hvm</type>
+ <loader>/usr/lib/xen/boot/hvmloader</loader>
+ <boot dev='hd'/>
+ </os>
+ <memory>524288</memory>
+ <vcpu>1</vcpu>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>restart</on_crash>
+ <features>
+ <pae/>
+ <acpi/>
+ <apic/>
+ </features>
+ <clock sync="localtime"/>
+ <devices>
+ <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
+ <interface type='bridge'>
+ <source bridge='xenbr0'/>
+ <mac address='00:16:3e:5d:c7:9e'/>
+ <script path='vif-bridge'/>
+ </interface>
+ <disk type='file'>
+ <source file='/var/lib/xen/images/fv0'/>
+ <target dev='hda'/>
+ </disk>
+ <disk type='file' device='cdrom'>
+ <source file='/var/lib/xen/images/fc5-x86_64-boot.iso'/>
+ <target dev='hdc'/>
+ <readonly/>
+ </disk>
+ <disk type='file' device='floppy'>
+ <source file='/root/fd.img'/>
+ <target dev='fda'/>
+ </disk>
+ <graphics type='vnc' port='5904'/>
+ </devices>
+ </domain>
+
+Fullyvirtualized guest direct kernel boot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With Xen 3.2.0 or later it is possible to bypass the BIOS and directly boot a
+Linux kernel and initrd as a fullyvirtualized domain. This allows for complete
+automation of OS installation, for example using the Anaconda kickstart support.
+
+::
+
+ <domain type='xen' id='3'>
+ <name>fv0</name>
+ <uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
+ <os>
+ <type>hvm</type>
+ <loader>/usr/lib/xen/boot/hvmloader</loader>
+ <kernel>/var/lib/xen/install/vmlinuz-fedora8-x86_64</kernel>
+ <initrd>/var/lib/xen/install/initrd-vmlinuz-fedora8-x86_64</initrd>
+ <cmdline> kickstart=http://example.com/myguest.ks </cmdline>
+ </os>
+ <memory>524288</memory>
+ <vcpu>1</vcpu>
+ <on_poweroff>destroy</on_poweroff>
+ <on_reboot>restart</on_reboot>
+ <on_crash>restart</on_crash>
+ <features>
+ <pae/>
+ <acpi/>
+ <apic/>
+ </features>
+ <clock sync="localtime"/>
+ <devices>
+ <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
+ <interface type='bridge'>
+ <source bridge='xenbr0'/>
+ <mac address='00:16:3e:5d:c7:9e'/>
+ <script path='vif-bridge'/>
+ </interface>
+ <disk type='file'>
+ <source file='/var/lib/xen/images/fv0'/>
+ <target dev='hda'/>
+ </disk>
+ <disk type='file' device='cdrom'>
+ <source file='/var/lib/xen/images/fc5-x86_64-boot.iso'/>
+ <target dev='hdc'/>
+ <readonly/>
+ </disk>
+ <disk type='file' device='floppy'>
+ <source file='/root/fd.img'/>
+ <target dev='fda'/>
+ </disk>
+ <graphics type='vnc' port='5904'/>
+ </devices>
+ </domain>
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 4fb2e1a9f4..95ace2677e 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -8352,5 +8352,5 @@ Example configs
Example configurations for each driver are provide on the driver specific pages
listed below
-- `Xen examples <drvxen.html#xmlconfig>`__
+- `Xen examples <drvxen.html#example-domain-xml-config>`__
- `QEMU/KVM examples <drvqemu.html#example-domain-xml-config>`__
diff --git a/docs/meson.build b/docs/meson.build
index 940fbedcfa..6147f85d16 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'drvxen',
'firewall',
'format',
'formatcaps',
@@ -81,6 +80,7 @@ docs_rst_files = [
'drvvbox',
'drvvirtuozzo',
'drvvmware',
+ 'drvxen',
'errors',
'formatbackup',
'formatcheckpoint',
--
2.35.1
8:07 a.m.
New subject: [PATCH 14/29] docs: Convert 'drvxen' page to rST
On Mon, Mar 28, 2022 at 02:10:29PM +0200, Peter Krempa wrote:
Fix the referenced anchor in 'formatdomain.rst' right away.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
...
+Fullyvirtualized guest BIOS boot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Fullyvirtualized guests use the emulated BIOS to boot off the primary harddisk,
nitpick: even though it has nothing to do with the conversion, I think we could
fix "fullyvirtualized" to "fully virtualized". (1 more occurrence a
few lines
later)
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
8:18 a.m.
New subject: [PATCH 14/29] docs: Convert 'drvxen' page to rST
On Fri, Apr 01, 2022 at 15:07:16 +0200, Erik Skultety wrote:
On Mon, Mar 28, 2022 at 02:10:29PM +0200, Peter Krempa wrote:
> Fix the referenced anchor in 'formatdomain.rst' right away.
>
> Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
> ---
...
> +Fullyvirtualized guest BIOS boot
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Fullyvirtualized guests use the emulated BIOS to boot off the primary harddisk,
nitpick: even though it has nothing to do with the conversion, I think we could
fix "fullyvirtualized" to "fully virtualized". (1 more occurrence a
few lines
later)
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
Good catch; I'll fix it in a separate commit
7:10 a.m.
New subject: [PATCH 15/29] docs: Convert 'firewall' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/firewall.html.in | 523 ------------------------------------------
docs/firewall.rst | 506 ++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 507 insertions(+), 524 deletions(-)
delete mode 100644 docs/firewall.html.in
create mode 100644 docs/firewall.rst
diff --git a/docs/firewall.html.in b/docs/firewall.html.in
deleted file mode 100644
index 15b4f397be..0000000000
--- a/docs/firewall.html.in
+++ /dev/null
@@ -1,523 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1 >Firewall and network filtering in libvirt</h1>
- <p>There are three pieces of libvirt functionality which do network
- filtering of some type.
- <br /><br />
- At a high level they are:
- </p>
- <ul>
- <li>The virtual network driver
- <br /><br />
- This provides an isolated bridge device (ie no physical NICs
- attached). Guest TAP devices are attached to this bridge.
- Guests can talk to each other and the host, and optionally the
- wider world.
- <br /><br />
- </li>
- <li>The QEMU driver MAC filtering
- <br /><br />
- This provides a generic filtering of MAC addresses to prevent
- the guest spoofing its MAC address. This is mostly obsoleted by
- the next item, so won't be discussed further.
- <br /><br />
- </li>
- <li>The network filter driver
- <br /><br />
- This provides fully configurable, arbitrary network filtering
- of traffic on guest NICs. Generic rulesets are defined at the
- host level to control traffic in some manner. Rules sets are
- then associated with individual NICs of a guest. While not as
- expressive as directly using iptables/ebtables, this can still
- do nearly everything you would want to on a guest NIC filter.
- </li>
- </ul>
-
- <h3><a id="fw-virtual-network-driver">The virtual network
driver</a>
- </h3>
- <p>The typical configuration for guests is to use bridging of the
- physical NIC on the host to connect the guest directly to the LAN.
- In RHEL6 there is also the possibility of using macvtap/sr-iov
- and VEPA connectivity. None of this stuff plays nicely with wireless
- NICs, since they will typically silently drop any traffic with a
- MAC address that doesn't match that of the physical NIC.
- </p>
- <p>Thus the virtual network driver in libvirt was invented. This takes
- the form of an isolated bridge device (ie one with no physical NICs
- attached). The TAP devices associated with the guest NICs are attached
- to the bridge device. This immediately allows guests on a single host
- to talk to each other and to the host OS (modulo host IPtables rules).
- </p>
- <p>libvirt then uses iptables to control what further connectivity is
- available. There are three configurations possible for a virtual
- network at time of writing:
- </p>
- <ul>
- <li>isolated: all off-node traffic is completely blocked</li>
- <li>nat: outbound traffic to the LAN is allowed, but MASQUERADED</li>
- <li>forward: outbound traffic to the LAN is allowed</li>
- </ul>
- <p>The latter 'forward' case requires the virtual network be on a
- separate sub-net from the main LAN, and that the LAN admin has
- configured routing for this subnet. In the future we intend to
- add support for IP subnetting and/or proxy-arp. This allows for
- the virtual network to use the same subnet as the main LAN and
- should avoid need for the LAN admin to configure special routing.
- </p>
- <p>Libvirt will optionally also provide DHCP services to the virtual
- network using DNSMASQ. In all cases, we need to allow DNS/DHCP
- queries to the host OS. Since we can't predict whether the host
- firewall setup is already allowing this, we insert 4 rules into
- the head of the INPUT chain
- </p>
- <pre>
-target prot opt in out source destination
-ACCEPT udp -- virbr0 * 0.0.0.0/0 0.0.0.0/0 udp dpt:53
-ACCEPT tcp -- virbr0 * 0.0.0.0/0 0.0.0.0/0 tcp dpt:53
-ACCEPT udp -- virbr0 * 0.0.0.0/0 0.0.0.0/0 udp dpt:67
-ACCEPT tcp -- virbr0 * 0.0.0.0/0 0.0.0.0/0 tcp
dpt:67</pre>
- <p>Note we have restricted our rules to just the bridge associated
- with the virtual network, to avoid opening undesirable holes in
- the host firewall wrt the LAN/WAN.
- </p>
- <p>The next rules depend on the type of connectivity allowed, and go
- in the main FORWARD chain:
- </p>
- <ul>
- <li>type=isolated
- <br /><br />
-Allow traffic between guests. Deny inbound. Deny outbound.
- <pre>
-target prot opt in out source destination
-ACCEPT all -- virbr1 virbr1 0.0.0.0/0 0.0.0.0/0
-REJECT all -- * virbr1 0.0.0.0/0 0.0.0.0/0 reject-with
icmp-port-unreachable
-REJECT all -- virbr1 * 0.0.0.0/0 0.0.0.0/0 reject-with
icmp-port-unreachable</pre>
- </li>
- <li>type=nat
- <br /><br />
-Allow inbound related to an established connection. Allow
-outbound, but only from our expected subnet. Allow traffic
-between guests. Deny all other inbound. Deny all other outbound.
- <pre>
-target prot opt in out source destination
-ACCEPT all -- * virbr0 0.0.0.0/0 192.168.122.0/24 state
RELATED,ESTABLISHED
-ACCEPT all -- virbr0 * 192.168.122.0/24 0.0.0.0/0
-ACCEPT all -- virbr0 virbr0 0.0.0.0/0 0.0.0.0/0
-REJECT all -- * virbr0 0.0.0.0/0 0.0.0.0/0 reject-with
icmp-port-unreachable
-REJECT all -- virbr0 * 0.0.0.0/0 0.0.0.0/0 reject-with
icmp-port-unreachable</pre>
- </li>
- <li>type=routed
- <br /><br />
-Allow inbound, but only to our expected subnet. Allow
-outbound, but only from our expected subnet. Allow traffic
-between guests. Deny all other inbound. Deny all other outbound.
- <pre>
-target prot opt in out source destination
-ACCEPT all -- * virbr2 0.0.0.0/0 192.168.124.0/24
-ACCEPT all -- virbr2 * 192.168.124.0/24 0.0.0.0/0
-ACCEPT all -- virbr2 virbr2 0.0.0.0/0 0.0.0.0/0
-REJECT all -- * virbr2 0.0.0.0/0 0.0.0.0/0 reject-with
icmp-port-unreachable
-REJECT all -- virbr2 * 0.0.0.0/0 0.0.0.0/0 reject-with
icmp-port-unreachable</pre>
- </li>
- <li>Finally, with type=nat, there is also an entry in the POSTROUTING
-chain to apply masquerading:
- <pre>
-target prot opt in out source destination
-MASQUERADE all -- * * 192.168.122.0/24 !192.168.122.0/24</pre>
- </li>
- </ul>
-
- <h3><a id="fw-firewalld-and-virtual-network-driver">firewalld
and the virtual network driver</a>
- </h3>
- <p>
- If <a href="https://firewalld.org">firewalld</a> is active
on
- the host, libvirt will attempt to place the bridge interface of
- a libvirt virtual network into the firewalld zone named
- "libvirt" (thus making all guest->host traffic on that network
- subject to the rules of the "libvirt" zone). This is done
- because, if firewalld is using its nftables backend (available
- since firewalld 0.6.0) the default firewalld zone (which would
- be used if libvirt didn't explicitly set the zone) prevents
- forwarding traffic from guests through the bridge, as well as
- preventing DHCP, DNS, and most other traffic from guests to
- host. The zone named "libvirt" is installed into the firewalld
- configuration by libvirt (not by firewalld), and allows
- forwarded traffic through the bridge as well as DHCP, DNS, TFTP,
- and SSH traffic to the host - depending on firewalld's backend
- this will be implemented via either iptables or nftables
- rules. libvirt's own rules outlined above will *always* be
- iptables rules regardless of which backend is in use by
- firewalld.
- </p>
- <p>
- NB: It is possible to manually set the firewalld zone for a
- network's interface with the "zone" attribute of the network's
- "bridge" element.
- </p>
- <p>
- NB: Prior to libvirt 5.1.0, the firewalld "libvirt" zone did not
- exist, and prior to firewalld 0.7.0 a feature crucial to making
- the "libvirt" zone operate properly (rich rule priority
- settings) was not implemented in firewalld. In cases where one
- or the other of the two packages is missing the necessary
- functionality, it's still possible to have functional guest
- networking by setting the firewalld backend to "iptables" (in
- firewalld prior to 0.6.0, this was the only backend available).
- </p>
-
- <h3><a id="fw-network-filter-driver">The network filter
driver</a>
- </h3>
- <p>This driver provides a fully configurable network filtering capability
- that leverages ebtables, iptables and ip6tables. This was written by
- the libvirt guys at IBM and although its XML schema is defined by libvirt,
- the conceptual model is closely aligned with the DMTF CIM schema for
- network filtering:
- </p>
- <p><a
href="https://www.dmtf.org/standards/cim/cim_schema_v2230/CIM_Networ...
- <p>The filters are managed in libvirt as a top level, standalone object.
- This allows the filters to then be referenced by any libvirt object
- that requires their functionality, instead tying them only to use
- by guest NICs. In the current implementation, filters can be associated
- with individual guest NICs via the libvirt domain XML format. In the
- future we might allow filters to be associated with the virtual network
- objects. Further we're expecting to define a new 'virtual switch'
object
- to remove the complexity of configuring bridge/sriov/vepa networking
- modes. This make also end up making use of network filters.
- </p>
- <p>There are a new set of virsh commands for managing network
filters:</p>
- <ul>
- <li>virsh nwfilter-define
- <br /><br />
- define or update a network filter from an XML file
- <br /><br />
- </li>
- <li>virsh nwfilter-undefine
- <br /><br />
- undefine a network filter
- <br /><br />
- </li>
- <li>virsh nwfilter-dumpxml
- <br /><br />
- network filter information in XML
- <br /><br />
- </li>
- <li>virsh nwfilter-list
- <br /><br />
- list network filters
- <br /><br />
- </li>
- <li>virsh nwfilter-edit
- <br /><br />
- edit XML configuration for a network filter
- </li>
- </ul>
- <p>There are equivalently named C APIs for each of these commands.</p>
- <p>As with all objects libvirt manages, network filters are configured
-using an XML format. At a high level the format looks like this:
- </p>
-<pre>
-<filter name='no-spamming' chain='XXXX'>
- <uuid>d217f2d7-5a04-0e01-8b98-ec2743436b74</uuid>
-
- <rule ...>
- ....
- </rule>
-
- <filterref filter='XXXX'/>
-</filter></pre>
- <p>Every filter has a name and UUID which serve as unique identifiers.
- A filter can have zero-or-more <code><rule></code>
elements which
- are used to actually define network controls. Filters can be arranged
- into a DAG, so zero-or-more <code><filterref/></code>
elements are
- also allowed. Cycles in the graph are not allowed.
- </p>
- <p>The <code><rule></code> element is where all the
interesting stuff
- happens. It has three attributes, an action, a traffic direction and an
- optional priority. E.g.:
- </p>
- <pre><rule action='drop' direction='out'
priority='500'></pre>
- <p>Within the rule there are a wide variety of elements allowed, which
- do protocol specific matching. Supported protocols currently include
- <code>mac</code>, <code>arp</code>,
<code>rarp</code>, <code>ip</code>,
- <code>ipv6</code>, <code>tcp/ip</code>,
<code>icmp/ip</code>,
- <code>igmp/ip</code>, <code>udp/ip</code>,
<code>udplite/ip</code>,
- <code>esp/ip</code>, <code>ah/ip</code>,
<code>sctp/ip</code>,
- <code>tcp/ipv6</code>, <code>icmp/ipv6</code>,
<code>igmp/ipv6</code>,
- <code>udp/ipv6</code>, <code>udplite/ipv6</code>,
<code>esp/ipv6</code>,
- <code>ah/ipv6</code>, <code>sctp/ipv6</code>. Each
protocol defines what
- is valid inside the <rule> element. The general pattern though is:
- </p>
- <pre>
-<protocol match='yes|no' attribute1='value1'
attribute2='value2'/></pre>
- <p>So, eg a TCP protocol, matching ports 0-1023 would be expressed
as:</p>
- <pre><tcp match='yes' srcportstart='0'
srcportend='1023'/></pre>
- <p>Attributes can included references to variables defined by the
- object using the rule. So the guest XML format allows each NIC
- to have a MAC address and IP address defined. These are made
- available to filters via the variables
<code><b>$IP</b></code> and
- <code><b>$MAC</b></code>.
- </p>
- <p>So to define a filter that prevents IP address spoofing we can
- simply match on source IP address <code>!= $IP</code> like this:
- </p>
- <pre>
-<filter name='no-ip-spoofing' chain='ipv4'>
- <rule action='drop' direction='out'>
- <ip match='no' srcipaddr='<b>$IP</b>' />
- </rule>
-</filter></pre>
- <p>I'm not going to go into details on all the other protocol
- matches you can do, because it'll take far too much space.
- You can read about the options
- <a href="formatnwfilter.html#nwfelemsRulesProto">here</a>.
- </p>
- <p>Out of the box in RHEL6/Fedora rawhide, libvirt ships with a
- set of default useful rules:
- </p>
- <pre>
-# virsh nwfilter-list
-UUID Name
-----------------------------------------------------------------
-15b1ab2b-b1ac-1be2-ed49-2042caba4abb allow-arp
-6c51a466-8d14-6d11-46b0-68b1a883d00f allow-dhcp
-7517ad6c-bd90-37c8-26c9-4eabcb69848d allow-dhcp-server
-7680776c-77aa-496f-90d6-13097664b925 allow-dhcpv6
-9cdaad60-7631-4172-8ccb-ef774be7485b allow-dhcpv6-server
-3d38b406-7cf0-8335-f5ff-4b9add35f288 allow-incoming-ipv4
-908543c1-902e-45f6-a6ca-1a0ad35e7599 allow-incoming-ipv6
-5ff06320-9228-2899-3db0-e32554933415 allow-ipv4
-ce8904cc-ad3a-4454-896c-53452882f817 allow-ipv6
-db0b1767-d62b-269b-ea96-0cc8b451144e clean-traffic
-6d6ddcc8-1242-4c43-ac63-63af80493132 clean-traffic-gateway
-4cf38077-c7d5-4e25-99bb-6c4c9efad294 no-arp-ip-spoofing
-0b11a636-ce58-497f-be90-17f63c92487a no-arp-mac-spoofing
-f88f1932-debf-4aa1-9fbe-f10d3aa4bc95 no-arp-spoofing
-772f112d-52e4-700c-0250-e178a3d91a7a no-ip-multicast
-7ee20370-8106-765d-f7ff-8a60d5aaf30b no-ip-spoofing
-f8a51c43-a08f-49b3-b9e2-393d54522dc0 no-ipv6-multicast
-a7f0afe9-a428-44b8-8566-c8ee2a669271 no-ipv6-spoofing
-d5d3c490-c2eb-68b1-24fc-3ee362fc8af3 no-mac-broadcast
-fb57c546-76dc-a372-513f-e8179011b48a no-mac-spoofing
-dba10ea7-446d-76de-346f-335bd99c1d05 no-other-l2-traffic
-f5c78134-9da4-0c60-a9f0-fb37bc21ac1f no-other-rarp-traffic
-7637e405-4ccf-42ac-5b41-14f8d03d8cf3 qemu-announce-self
-9aed52e7-f0f3-343e-fe5c-7dcb27b594e5 qemu-announce-self-rarp</pre>
- <p>Most of these are just building blocks. The interesting one here
- is 'clean-traffic'. This pulls together all the building blocks
- into one filter that you can then associate with a guest NIC.
- This stops the most common bad things a guest might try, IP
- spoofing, arp spoofing and MAC spoofing. To look at the rules for
- any of these just do:
- </p>
- <pre>virsh nwfilter-dumpxml FILTERNAME|UUID</pre>
- <p>They are all stored in <code>/etc/libvirt/nwfilter</code>, but
don't
- edit the files there directly. Use <code>virsh nwfilter-define</code>
- to update them. This ensures the guests have their iptables/ebtables
- rules recreated.
- </p>
- <p>To associate the clean-traffic filter with a guest, edit the
- guest XML config and change the <code><interface></code>
element
- to include a <code><filterref></code> and also specify
the
- <code><ip address/></code> that the guest is allowed to
- use:
- </p>
- <pre>
-<interface type='bridge'>
- <mac address='52:54:00:56:44:32'/>
- <source bridge='br1'/>
- <ip address='10.33.8.131'/>
- <target dev='vnet0'/>
- <model type='virtio'/>
- <filterref filter='clean-traffic'/>
-</interface></pre>
- <p>If no <code><ip address></code> is included, the
network filter
- driver will activate its 'learning mode'. This uses libpcap to snoop on
- network traffic the guest sends and attempts to identify the
- first IP address it uses. It then locks traffic to this address.
- Obviously this isn't entirely secure, but it does offer some
- protection against the guest being trojaned once up and running.
- In the future we intend to enhance the learning mode so that it
- looks for DHCPOFFERS from a trusted DHCP server and only allows
- the offered IP address to be used.
- </p>
- <p>Now, how is all this implemented...?</p>
- <p>The network filter driver uses a combination of ebtables, iptables and
- ip6tables, depending on which protocols are referenced in a filter. The
- out of the box 'clean-traffic' filter rules only require use of
- ebtables. If you want to do matching at tcp/udp/etc protocols (eg to add
- a new filter 'no-email-spamming' to block port 25), then iptables will
- also be used.
- </p>
- <p>The driver attempts to keep its rules separate from those that
- the host admin might already have configured. So the first thing
- it does with ebtables, is to add two hooks in POSTROUTING and
- PREROUTING chains, to redirect traffic to custom chains. These
- hooks match on the TAP device name of the guest NIC, so they
- should not interact badly with any administrator defined rules:
- </p>
- <pre>
-Bridge chain: PREROUTING, entries: 1, policy: ACCEPT
--i vnet0 -j libvirt-I-vnet0
-
-Bridge chain: POSTROUTING, entries: 1, policy: ACCEPT
--o vnet0 -j libvirt-O-vnet0</pre>
- <p>To keep things manageable and easy to follow, the driver will then
- create further sub-chains for each protocol then it needs to match
- against:
- </p>
- <pre>
-Bridge chain: libvirt-I-vnet0, entries: 5, policy: ACCEPT
--p IPv4 -j I-vnet0-ipv4
--p ARP -j I-vnet0-arp
--p 0x8035 -j I-vnet0-rarp
--p 0x835 -j ACCEPT
--j DROP
-
-Bridge chain: libvirt-O-vnet0, entries: 4, policy: ACCEPT
--p IPv4 -j O-vnet0-ipv4
--p ARP -j O-vnet0-arp
--p 0x8035 -j O-vnet0-rarp
--j DROP</pre>
- <p>Finally, here comes the actual implementation of the filters. This
- example shows the 'clean-traffic' filter implementation.
- I'm not going to explain what this is doing now. :-)
- </p>
- <pre>
-Bridge chain: I-vnet0-ipv4, entries: 2, policy: ACCEPT
--s ! 52:54:0:56:44:32 -j DROP
--p IPv4 --ip-src ! 10.33.8.131 -j DROP
-
-Bridge chain: O-vnet0-ipv4, entries: 1, policy: ACCEPT
--j ACCEPT
-
-Bridge chain: I-vnet0-arp, entries: 6, policy: ACCEPT
--s ! 52:54:0:56:44:32 -j DROP
--p ARP --arp-mac-src ! 52:54:0:56:44:32 -j DROP
--p ARP --arp-ip-src ! 10.33.8.131 -j DROP
--p ARP --arp-op Request -j ACCEPT
--p ARP --arp-op Reply -j ACCEPT
--j DROP
-
-Bridge chain: O-vnet0-arp, entries: 5, policy: ACCEPT
--p ARP --arp-op Reply --arp-mac-dst ! 52:54:0:56:44:32 -j DROP
--p ARP --arp-ip-dst ! 10.33.8.131 -j DROP
--p ARP --arp-op Request -j ACCEPT
--p ARP --arp-op Reply -j ACCEPT
--j DROP
-
-Bridge chain: I-vnet0-rarp, entries: 2, policy: ACCEPT
--p 0x8035 -s 52:54:0:56:44:32 -d Broadcast --arp-op Request_Reverse --arp-ip-src 0.0.0.0
--arp-ip-dst 0.0.0.0 --arp-mac-src 52:54:0:56:44:32 --arp-mac-dst 52:54:0:56:44:32 -j
ACCEPT
--j DROP
-
-Bridge chain: O-vnet0-rarp, entries: 2, policy: ACCEPT
--p 0x8035 -d Broadcast --arp-op Request_Reverse --arp-ip-src 0.0.0.0 --arp-ip-dst 0.0.0.0
--arp-mac-src 52:54:0:56:44:32 --arp-mac-dst 52:54:0:56:44:32 -j ACCEPT
--j DROP</pre>
- <p>NB, we would have liked to include the prefix 'libvirt-' in all
- of our chain names, but unfortunately the kernel limits names
- to a very short maximum length. So only the first two custom
- chains can include that prefix. The others just include the
- TAP device name + protocol name.
- </p>
- <p>If I define a new filter 'no-spamming' and then add this to the
- 'clean-traffic' filter, I can illustrate how iptables usage works:
- </p>
- <pre>
-# cat > /root/spamming.xml <<EOF
-<filter name='no-spamming' chain='root'>
- <uuid>d217f2d7-5a04-0e01-8b98-ec2743436b74</uuid>
- <rule action='drop' direction='out'
priority='500'>
- <tcp dstportstart='25' dstportend='25'/>
- </rule>
-</filter>
-EOF
-# virsh nwfilter-define /root/spamming.xml
-# virsh nwfilter-edit clean-traffic</pre>
-
- <p>...add <code><filterref
filter='no-spamming'/></code></p>
- <p>All active guests immediately have their iptables/ebtables rules
- rebuilt.
- </p>
- <p>The network filter driver deals with iptables in a very similar
- way. First it separates out its rules from those the admin may
- have defined, by adding a couple of hooks into the INPUT/FORWARD
- chains:
- </p>
- <pre>
-Chain INPUT (policy ACCEPT 13M packets, 21G bytes)
-target prot opt in out source destination
-libvirt-host-in all -- * * 0.0.0.0/0 0.0.0.0/0
-
-Chain FORWARD (policy ACCEPT 5532K packets, 3010M bytes)
-target prot opt in out source destination
-libvirt-in all -- * * 0.0.0.0/0 0.0.0.0/0
-libvirt-out all -- * * 0.0.0.0/0 0.0.0.0/0
-libvirt-in-post all -- * * 0.0.0.0/0 0.0.0.0/0</pre>
- <p>These custom chains then do matching based on the TAP device
- name, so they won't open holes in the admin defined matches for
- the LAN/WAN (if any).
- </p>
- <pre>
-Chain libvirt-host-in (1 references)
- target prot opt in out source destination
- HI-vnet0 all -- * * 0.0.0.0/0 0.0.0.0/0 [goto]
PHYSDEV match --physdev-in vnet0
-
-Chain libvirt-in (1 references)
- target prot opt in out source destination
- FI-vnet0 all -- * * 0.0.0.0/0 0.0.0.0/0 [goto]
PHYSDEV match --physdev-in vnet0
-
-Chain libvirt-in-post (1 references)
- target prot opt in out source destination
- ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0 PHYSDEV
match --physdev-in vnet0
-
-Chain libvirt-out (1 references)
- target prot opt in out source destination
- FO-vnet0 all -- * * 0.0.0.0/0 0.0.0.0/0 [goto]
PHYSDEV match --physdev-out vnet0</pre>
- <p>Finally, we can see the interesting bit which is the actual
- implementation of my filter to block port 25 access:
- </p>
- <pre>
-Chain FI-vnet0 (1 references)
- target prot opt in out source destination
- DROP tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:25
-
-Chain FO-vnet0 (1 references)
- target prot opt in out source destination
- DROP tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp spt:25
-
-Chain HI-vnet0 (1 references)
- target prot opt in out source destination
- DROP tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp
dpt:25</pre>
- <p>One thing in looking at this you may notice is that if there
- are many guests all using the same filters, we will be duplicating
- the iptables rules over and over for each guest. This is merely a
- limitation of the current rules engine implementation. At the libvirt
- object modelling level you can clearly see we've designed the model
- so filter rules are defined in one place, and indirectly referenced
- by guests. Thus it should be possible to change the implementation in
- the future so we can share the actual iptables/ebtables rules for
- each guest to create a more scalable system. The stuff in current libvirt
- is more or less the very first working implementation we've had of this,
- so there's not been much optimization work done yet.
- </p>
- <p>Also notice that at the XML level we don't expose the fact we
- are using iptables or ebtables at all. The rule definition is done in
- terms of network protocols. Thus if we ever find a need, we could
- plug in an alternative implementation that calls out to a different
- firewall implementation instead of ebtables/iptables (providing that
- implementation was suitably expressive of course)
- </p>
- <p>Finally, in terms of problems we have in deployment. The biggest
- problem is that if the admin does <code>service iptables
restart</code>
- all our work gets blown away. We've experimented with using lokkit
- to record our custom rules in a persistent config file, but that
- caused different problem. Admins who were not using lokkit for
- their config found that all their own rules got blown away. So
- we threw away our lokkit code. Instead we document that if you
- run <code>service iptables restart</code>, you need to send SIGHUP to
- libvirt to make it recreate its rules.
- </p>
- <p>More in depth documentation on this is <a
href="formatnwfilter.html">here</a>.</p>
- </body>
-</html>
diff --git a/docs/firewall.rst b/docs/firewall.rst
new file mode 100644
index 0000000000..adda0ef1f4
--- /dev/null
+++ b/docs/firewall.rst
@@ -0,0 +1,506 @@
+=========================================
+Firewall and network filtering in libvirt
+=========================================
+
+.. contents::
+
+There are three pieces of libvirt functionality which do network filtering of
+some type. At a high level they are:
+
+- The virtual network driver
+
+ This provides an isolated bridge device (ie no physical NICs attached).
+ Guest TAP devices are attached to this bridge. Guests can talk to each
+ other and the host, and optionally the wider world.
+
+- The QEMU driver MAC filtering
+
+ This provides a generic filtering of MAC addresses to prevent the guest
+ spoofing its MAC address. This is mostly obsoleted by the next item, so
+ won't be discussed further.
+
+- The network filter driver
+
+ This provides fully configurable, arbitrary network filtering of traffic on
+ guest NICs. Generic rulesets are defined at the host level to control
+ traffic in some manner. Rules sets are then associated with individual NICs
+ of a guest. While not as expressive as directly using iptables/ebtables,
+ this can still do nearly everything you would want to on a guest NIC
+ filter.
+
+The virtual network driver
+--------------------------
+
+The typical configuration for guests is to use bridging of the physical NIC on
+the host to connect the guest directly to the LAN. In RHEL6 there is also the
+possibility of using macvtap/sr-iov and VEPA connectivity. None of this stuff
+plays nicely with wireless NICs, since they will typically silently drop any
+traffic with a MAC address that doesn't match that of the physical NIC.
+
+Thus the virtual network driver in libvirt was invented. This takes the form of
+an isolated bridge device (ie one with no physical NICs attached). The TAP
+devices associated with the guest NICs are attached to the bridge device. This
+immediately allows guests on a single host to talk to each other and to the host
+OS (modulo host IPtables rules).
+
+libvirt then uses iptables to control what further connectivity is available.
+There are three configurations possible for a virtual network at time of
+writing:
+
+- isolated: all off-node traffic is completely blocked
+- nat: outbound traffic to the LAN is allowed, but MASQUERADED
+- forward: outbound traffic to the LAN is allowed
+
+The latter 'forward' case requires the virtual network be on a separate sub-net
+from the main LAN, and that the LAN admin has configured routing for this
+subnet. In the future we intend to add support for IP subnetting and/or
+proxy-arp. This allows for the virtual network to use the same subnet as the
+main LAN and should avoid need for the LAN admin to configure special routing.
+
+Libvirt will optionally also provide DHCP services to the virtual network using
+DNSMASQ. In all cases, we need to allow DNS/DHCP queries to the host OS. Since
+we can't predict whether the host firewall setup is already allowing this, we
+insert 4 rules into the head of the INPUT chain
+
+::
+
+ target prot opt in out source destination
+ ACCEPT udp -- virbr0 * 0.0.0.0/0 0.0.0.0/0 udp
dpt:53
+ ACCEPT tcp -- virbr0 * 0.0.0.0/0 0.0.0.0/0 tcp
dpt:53
+ ACCEPT udp -- virbr0 * 0.0.0.0/0 0.0.0.0/0 udp
dpt:67
+ ACCEPT tcp -- virbr0 * 0.0.0.0/0 0.0.0.0/0 tcp
dpt:67
+
+Note we have restricted our rules to just the bridge associated with the virtual
+network, to avoid opening undesirable holes in the host firewall wrt the
+LAN/WAN.
+
+The next rules depend on the type of connectivity allowed, and go in the main
+FORWARD chain:
+
+- | type=isolated
+ | Allow traffic between guests. Deny inbound. Deny outbound.
+
+ ::
+
+ target prot opt in out source destination
+ ACCEPT all -- virbr1 virbr1 0.0.0.0/0 0.0.0.0/0
+ REJECT all -- * virbr1 0.0.0.0/0 0.0.0.0/0
reject-with icmp-port-unreachable
+ REJECT all -- virbr1 * 0.0.0.0/0 0.0.0.0/0
reject-with icmp-port-unreachable
+
+- | type=nat
+ | Allow inbound related to an established connection. Allow outbound, but
+ only from our expected subnet. Allow traffic between guests. Deny all other
+ inbound. Deny all other outbound.
+
+ ::
+
+ target prot opt in out source destination
+ ACCEPT all -- * virbr0 0.0.0.0/0 192.168.122.0/24 state
RELATED,ESTABLISHED
+ ACCEPT all -- virbr0 * 192.168.122.0/24 0.0.0.0/0
+ ACCEPT all -- virbr0 virbr0 0.0.0.0/0 0.0.0.0/0
+ REJECT all -- * virbr0 0.0.0.0/0 0.0.0.0/0
reject-with icmp-port-unreachable
+ REJECT all -- virbr0 * 0.0.0.0/0 0.0.0.0/0
reject-with icmp-port-unreachable
+
+- | type=routed
+ | Allow inbound, but only to our expected subnet. Allow outbound, but only
+ from our expected subnet. Allow traffic between guests. Deny all other
+ inbound. Deny all other outbound.
+
+ ::
+
+ target prot opt in out source destination
+ ACCEPT all -- * virbr2 0.0.0.0/0 192.168.124.0/24
+ ACCEPT all -- virbr2 * 192.168.124.0/24 0.0.0.0/0
+ ACCEPT all -- virbr2 virbr2 0.0.0.0/0 0.0.0.0/0
+ REJECT all -- * virbr2 0.0.0.0/0 0.0.0.0/0
reject-with icmp-port-unreachable
+ REJECT all -- virbr2 * 0.0.0.0/0 0.0.0.0/0
reject-with icmp-port-unreachable
+
+- Finally, with type=nat, there is also an entry in the POSTROUTING chain to
+ apply masquerading:
+
+ ::
+
+ target prot opt in out source destination
+ MASQUERADE all -- * * 192.168.122.0/24 !192.168.122.0/24
+
+firewalld and the virtual network driver
+----------------------------------------
+
+If `firewalld <https://firewalld.org>`__ is active on the host, libvirt will
+attempt to place the bridge interface of a libvirt virtual network into the
+firewalld zone named "libvirt" (thus making all guest->host traffic on that
+network subject to the rules of the "libvirt" zone). This is done because, if
+firewalld is using its nftables backend (available since firewalld 0.6.0) the
+default firewalld zone (which would be used if libvirt didn't explicitly set the
+zone) prevents forwarding traffic from guests through the bridge, as well as
+preventing DHCP, DNS, and most other traffic from guests to host. The zone named
+"libvirt" is installed into the firewalld configuration by libvirt (not by
+firewalld), and allows forwarded traffic through the bridge as well as DHCP,
+DNS, TFTP, and SSH traffic to the host - depending on firewalld's backend this
+will be implemented via either iptables or nftables rules. libvirt's own rules
+outlined above will \*always\* be iptables rules regardless of which backend is
+in use by firewalld.
+
+NB: It is possible to manually set the firewalld zone for a network's interface
+with the "zone" attribute of the network's "bridge" element.
+
+NB: Prior to libvirt 5.1.0, the firewalld "libvirt" zone did not exist, and
+prior to firewalld 0.7.0 a feature crucial to making the "libvirt" zone
operate
+properly (rich rule priority settings) was not implemented in firewalld. In
+cases where one or the other of the two packages is missing the necessary
+functionality, it's still possible to have functional guest networking by
+setting the firewalld backend to "iptables" (in firewalld prior to 0.6.0, this
+was the only backend available).
+
+The network filter driver
+-------------------------
+
+This driver provides a fully configurable network filtering capability that
+leverages ebtables, iptables and ip6tables. This was written by the libvirt guys
+at IBM and although its XML schema is defined by libvirt, the conceptual model
+is closely aligned with the DMTF CIM schema for network filtering:
+
+https://www.dmtf.org/standards/cim/cim_schema_v2230/CIM_Network.pdf
+
+The filters are managed in libvirt as a top level, standalone object. This
+allows the filters to then be referenced by any libvirt object that requires
+their functionality, instead tying them only to use by guest NICs. In the
+current implementation, filters can be associated with individual guest NICs via
+the libvirt domain XML format. In the future we might allow filters to be
+associated with the virtual network objects. Further we're expecting to define a
+new 'virtual switch' object to remove the complexity of configuring
+bridge/sriov/vepa networking modes. This make also end up making use of network
+filters.
+
+There are a new set of virsh commands for managing network filters:
+
+- ``virsh nwfilter-define``
+ define or update a network filter from an XML file
+- ``virsh nwfilter-undefine``
+ undefine a network filter
+- ``virsh nwfilter-dumpxml``
+ network filter information in XML
+- ``virsh nwfilter-list``
+ list network filters
+- ``virsh nwfilter-edit``
+ edit XML configuration for a network filter
+
+There are equivalently named C APIs for each of these commands.
+
+As with all objects libvirt manages, network filters are configured using an XML
+format. At a high level the format looks like this:
+
+::
+
+ <filter name='no-spamming' chain='XXXX'>
+ <uuid>d217f2d7-5a04-0e01-8b98-ec2743436b74</uuid>
+
+ <rule ...>
+ ....
+ </rule>
+
+ <filterref filter='XXXX'/>
+ </filter>
+
+Every filter has a name and UUID which serve as unique identifiers. A filter can
+have zero-or-more ``<rule>`` elements which are used to actually define network
+controls. Filters can be arranged into a DAG, so zero-or-more ``<filterref/>``
+elements are also allowed. Cycles in the graph are not allowed.
+
+The ``<rule>`` element is where all the interesting stuff happens. It has three
+attributes, an action, a traffic direction and an optional priority. E.g.:
+
+::
+
+ <rule action='drop' direction='out' priority='500'>
+
+Within the rule there are a wide variety of elements allowed, which do protocol
+specific matching. Supported protocols currently include ``mac``, ``arp``,
+``rarp``, ``ip``, ``ipv6``, ``tcp/ip``, ``icmp/ip``, ``igmp/ip``, ``udp/ip``,
+``udplite/ip``, ``esp/ip``, ``ah/ip``, ``sctp/ip``, ``tcp/ipv6``, ``icmp/ipv6``,
+``igmp/ipv6``, ``udp/ipv6``, ``udplite/ipv6``, ``esp/ipv6``, ``ah/ipv6``,
+``sctp/ipv6``. Each protocol defines what is valid inside the <rule> element.
+The general pattern though is:
+
+::
+
+ <protocol match='yes|no' attribute1='value1'
attribute2='value2'/>
+
+So, eg a TCP protocol, matching ports 0-1023 would be expressed as:
+
+::
+
+ <tcp match='yes' srcportstart='0' srcportend='1023'/>
+
+Attributes can included references to variables defined by the object using the
+rule. So the guest XML format allows each NIC to have a MAC address and IP
+address defined. These are made available to filters via the variables ``$IP``
+and ``$MAC``.
+
+So to define a filter that prevents IP address spoofing we can simply match on
+source IP address ``!= $IP`` like this:
+
+::
+
+ <filter name='no-ip-spoofing' chain='ipv4'>
+ <rule action='drop' direction='out'>
+ <ip match='no' srcipaddr='$IP' />
+ </rule>
+ </filter>
+
+I'm not going to go into details on all the other protocol matches you can do,
+because it'll take far too much space. You can read about the options
+`here <formatnwfilter.html#nwfelemsRulesProto>`__.
+
+Out of the box in RHEL6/Fedora rawhide, libvirt ships with a set of default
+useful rules:
+
+::
+
+ # virsh nwfilter-list
+ UUID Name
+ ----------------------------------------------------------------
+ 15b1ab2b-b1ac-1be2-ed49-2042caba4abb allow-arp
+ 6c51a466-8d14-6d11-46b0-68b1a883d00f allow-dhcp
+ 7517ad6c-bd90-37c8-26c9-4eabcb69848d allow-dhcp-server
+ 7680776c-77aa-496f-90d6-13097664b925 allow-dhcpv6
+ 9cdaad60-7631-4172-8ccb-ef774be7485b allow-dhcpv6-server
+ 3d38b406-7cf0-8335-f5ff-4b9add35f288 allow-incoming-ipv4
+ 908543c1-902e-45f6-a6ca-1a0ad35e7599 allow-incoming-ipv6
+ 5ff06320-9228-2899-3db0-e32554933415 allow-ipv4
+ ce8904cc-ad3a-4454-896c-53452882f817 allow-ipv6
+ db0b1767-d62b-269b-ea96-0cc8b451144e clean-traffic
+ 6d6ddcc8-1242-4c43-ac63-63af80493132 clean-traffic-gateway
+ 4cf38077-c7d5-4e25-99bb-6c4c9efad294 no-arp-ip-spoofing
+ 0b11a636-ce58-497f-be90-17f63c92487a no-arp-mac-spoofing
+ f88f1932-debf-4aa1-9fbe-f10d3aa4bc95 no-arp-spoofing
+ 772f112d-52e4-700c-0250-e178a3d91a7a no-ip-multicast
+ 7ee20370-8106-765d-f7ff-8a60d5aaf30b no-ip-spoofing
+ f8a51c43-a08f-49b3-b9e2-393d54522dc0 no-ipv6-multicast
+ a7f0afe9-a428-44b8-8566-c8ee2a669271 no-ipv6-spoofing
+ d5d3c490-c2eb-68b1-24fc-3ee362fc8af3 no-mac-broadcast
+ fb57c546-76dc-a372-513f-e8179011b48a no-mac-spoofing
+ dba10ea7-446d-76de-346f-335bd99c1d05 no-other-l2-traffic
+ f5c78134-9da4-0c60-a9f0-fb37bc21ac1f no-other-rarp-traffic
+ 7637e405-4ccf-42ac-5b41-14f8d03d8cf3 qemu-announce-self
+ 9aed52e7-f0f3-343e-fe5c-7dcb27b594e5 qemu-announce-self-rarp
+
+Most of these are just building blocks. The interesting one here is
+'clean-traffic'. This pulls together all the building blocks into one filter
+that you can then associate with a guest NIC. This stops the most common bad
+things a guest might try, IP spoofing, arp spoofing and MAC spoofing. To look at
+the rules for any of these just do:
+
+::
+
+ virsh nwfilter-dumpxml FILTERNAME|UUID
+
+They are all stored in ``/etc/libvirt/nwfilter``, but don't edit the files there
+directly. Use ``virsh nwfilter-define`` to update them. This ensures the guests
+have their iptables/ebtables rules recreated.
+
+To associate the clean-traffic filter with a guest, edit the guest XML config
+and change the ``<interface>`` element to include a ``<filterref>`` and also
+specify the ``<ip address/>`` that the guest is allowed to use:
+
+::
+
+ <interface type='bridge'>
+ <mac address='52:54:00:56:44:32'/>
+ <source bridge='br1'/>
+ <ip address='10.33.8.131'/>
+ <target dev='vnet0'/>
+ <model type='virtio'/>
+ <filterref filter='clean-traffic'/>
+ </interface>
+
+If no ``<ip address>`` is included, the network filter driver will activate its
+'learning mode'. This uses libpcap to snoop on network traffic the guest sends
+and attempts to identify the first IP address it uses. It then locks traffic to
+this address. Obviously this isn't entirely secure, but it does offer some
+protection against the guest being trojaned once up and running. In the future
+we intend to enhance the learning mode so that it looks for DHCPOFFERS from a
+trusted DHCP server and only allows the offered IP address to be used.
+
+Now, how is all this implemented...?
+
+The network filter driver uses a combination of ebtables, iptables and
+ip6tables, depending on which protocols are referenced in a filter. The out of
+the box 'clean-traffic' filter rules only require use of ebtables. If you want
+to do matching at tcp/udp/etc protocols (eg to add a new filter
+'no-email-spamming' to block port 25), then iptables will also be used.
+
+The driver attempts to keep its rules separate from those that the host admin
+might already have configured. So the first thing it does with ebtables, is to
+add two hooks in POSTROUTING and PREROUTING chains, to redirect traffic to
+custom chains. These hooks match on the TAP device name of the guest NIC, so
+they should not interact badly with any administrator defined rules:
+
+::
+
+ Bridge chain: PREROUTING, entries: 1, policy: ACCEPT
+ -i vnet0 -j libvirt-I-vnet0
+
+ Bridge chain: POSTROUTING, entries: 1, policy: ACCEPT
+ -o vnet0 -j libvirt-O-vnet0
+
+To keep things manageable and easy to follow, the driver will then create
+further sub-chains for each protocol then it needs to match against:
+
+::
+
+ Bridge chain: libvirt-I-vnet0, entries: 5, policy: ACCEPT
+ -p IPv4 -j I-vnet0-ipv4
+ -p ARP -j I-vnet0-arp
+ -p 0x8035 -j I-vnet0-rarp
+ -p 0x835 -j ACCEPT
+ -j DROP
+
+ Bridge chain: libvirt-O-vnet0, entries: 4, policy: ACCEPT
+ -p IPv4 -j O-vnet0-ipv4
+ -p ARP -j O-vnet0-arp
+ -p 0x8035 -j O-vnet0-rarp
+ -j DROP
+
+Finally, here comes the actual implementation of the filters. This example shows
+the 'clean-traffic' filter implementation. I'm not going to explain what this
is
+doing now. :-)
+
+::
+
+ Bridge chain: I-vnet0-ipv4, entries: 2, policy: ACCEPT
+ -s ! 52:54:0:56:44:32 -j DROP
+ -p IPv4 --ip-src ! 10.33.8.131 -j DROP
+
+ Bridge chain: O-vnet0-ipv4, entries: 1, policy: ACCEPT
+ -j ACCEPT
+
+ Bridge chain: I-vnet0-arp, entries: 6, policy: ACCEPT
+ -s ! 52:54:0:56:44:32 -j DROP
+ -p ARP --arp-mac-src ! 52:54:0:56:44:32 -j DROP
+ -p ARP --arp-ip-src ! 10.33.8.131 -j DROP
+ -p ARP --arp-op Request -j ACCEPT
+ -p ARP --arp-op Reply -j ACCEPT
+ -j DROP
+
+ Bridge chain: O-vnet0-arp, entries: 5, policy: ACCEPT
+ -p ARP --arp-op Reply --arp-mac-dst ! 52:54:0:56:44:32 -j DROP
+ -p ARP --arp-ip-dst ! 10.33.8.131 -j DROP
+ -p ARP --arp-op Request -j ACCEPT
+ -p ARP --arp-op Reply -j ACCEPT
+ -j DROP
+
+ Bridge chain: I-vnet0-rarp, entries: 2, policy: ACCEPT
+ -p 0x8035 -s 52:54:0:56:44:32 -d Broadcast --arp-op Request_Reverse --arp-ip-src
0.0.0.0 --arp-ip-dst 0.0.0.0 --arp-mac-src 52:54:0:56:44:32 --arp-mac-dst 52:54:0:56:44:32
-j ACCEPT
+ -j DROP
+
+ Bridge chain: O-vnet0-rarp, entries: 2, policy: ACCEPT
+ -p 0x8035 -d Broadcast --arp-op Request_Reverse --arp-ip-src 0.0.0.0 --arp-ip-dst
0.0.0.0 --arp-mac-src 52:54:0:56:44:32 --arp-mac-dst 52:54:0:56:44:32 -j ACCEPT
+ -j DROP
+
+NB, we would have liked to include the prefix 'libvirt-' in all of our chain
+names, but unfortunately the kernel limits names to a very short maximum length.
+So only the first two custom chains can include that prefix. The others just
+include the TAP device name + protocol name.
+
+If I define a new filter 'no-spamming' and then add this to the
'clean-traffic'
+filter, I can illustrate how iptables usage works:
+
+::
+
+ # cat > /root/spamming.xml <<EOF
+ <filter name='no-spamming' chain='root'>
+ <uuid>d217f2d7-5a04-0e01-8b98-ec2743436b74</uuid>
+ <rule action='drop' direction='out' priority='500'>
+ <tcp dstportstart='25' dstportend='25'/>
+ </rule>
+ </filter>
+ EOF
+ # virsh nwfilter-define /root/spamming.xml
+ # virsh nwfilter-edit clean-traffic
+
+...add ``<filterref filter='no-spamming'/>``
+
+All active guests immediately have their iptables/ebtables rules rebuilt.
+
+The network filter driver deals with iptables in a very similar way. First it
+separates out its rules from those the admin may have defined, by adding a
+couple of hooks into the INPUT/FORWARD chains:
+
+::
+
+ Chain INPUT (policy ACCEPT 13M packets, 21G bytes)
+ target prot opt in out source destination
+ libvirt-host-in all -- * * 0.0.0.0/0 0.0.0.0/0
+
+ Chain FORWARD (policy ACCEPT 5532K packets, 3010M bytes)
+ target prot opt in out source destination
+ libvirt-in all -- * * 0.0.0.0/0 0.0.0.0/0
+ libvirt-out all -- * * 0.0.0.0/0 0.0.0.0/0
+ libvirt-in-post all -- * * 0.0.0.0/0 0.0.0.0/0
+
+These custom chains then do matching based on the TAP device name, so they won't
+open holes in the admin defined matches for the LAN/WAN (if any).
+
+::
+
+ Chain libvirt-host-in (1 references)
+ target prot opt in out source destination
+ HI-vnet0 all -- * * 0.0.0.0/0 0.0.0.0/0 [goto]
PHYSDEV match --physdev-in vnet0
+
+ Chain libvirt-in (1 references)
+ target prot opt in out source destination
+ FI-vnet0 all -- * * 0.0.0.0/0 0.0.0.0/0 [goto]
PHYSDEV match --physdev-in vnet0
+
+ Chain libvirt-in-post (1 references)
+ target prot opt in out source destination
+ ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0 PHYSDEV
match --physdev-in vnet0
+
+ Chain libvirt-out (1 references)
+ target prot opt in out source destination
+ FO-vnet0 all -- * * 0.0.0.0/0 0.0.0.0/0 [goto]
PHYSDEV match --physdev-out vnet0
+
+Finally, we can see the interesting bit which is the actual implementation of my
+filter to block port 25 access:
+
+::
+
+ Chain FI-vnet0 (1 references)
+ target prot opt in out source destination
+ DROP tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp
dpt:25
+
+ Chain FO-vnet0 (1 references)
+ target prot opt in out source destination
+ DROP tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp
spt:25
+
+ Chain HI-vnet0 (1 references)
+ target prot opt in out source destination
+ DROP tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp
dpt:25
+
+One thing in looking at this you may notice is that if there are many guests all
+using the same filters, we will be duplicating the iptables rules over and over
+for each guest. This is merely a limitation of the current rules engine
+implementation. At the libvirt object modelling level you can clearly see we've
+designed the model so filter rules are defined in one place, and indirectly
+referenced by guests. Thus it should be possible to change the implementation in
+the future so we can share the actual iptables/ebtables rules for each guest to
+create a more scalable system. The stuff in current libvirt is more or less the
+very first working implementation we've had of this, so there's not been much
+optimization work done yet.
+
+Also notice that at the XML level we don't expose the fact we are using iptables
+or ebtables at all. The rule definition is done in terms of network protocols.
+Thus if we ever find a need, we could plug in an alternative implementation that
+calls out to a different firewall implementation instead of ebtables/iptables
+(providing that implementation was suitably expressive of course)
+
+Finally, in terms of problems we have in deployment. The biggest problem is that
+if the admin does ``service iptables restart`` all our work gets blown away.
+We've experimented with using lokkit to record our custom rules in a persistent
+config file, but that caused different problem. Admins who were not using lokkit
+for their config found that all their own rules got blown away. So we threw away
+our lokkit code. Instead we document that if you run
+``service iptables restart``, you need to send SIGHUP to libvirt to make it
+recreate its rules.
+
+More in depth documentation on this is `here <formatnwfilter.html>`__.
diff --git a/docs/meson.build b/docs/meson.build
index 6147f85d16..aa8bad89f0 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'firewall',
'format',
'formatcaps',
'formatdomaincaps',
@@ -82,6 +81,7 @@ docs_rst_files = [
'drvvmware',
'drvxen',
'errors',
+ 'firewall',
'formatbackup',
'formatcheckpoint',
'formatdomain',
--
2.35.1
7:10 a.m.
New subject: [PATCH 16/29] docs: Convert 'format' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/format.html.in | 48 ---------------------------------------------
docs/format.rst | 35 +++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 36 insertions(+), 49 deletions(-)
delete mode 100644 docs/format.html.in
create mode 100644 docs/format.rst
diff --git a/docs/format.html.in b/docs/format.html.in
deleted file mode 100644
index 1d2456de6f..0000000000
--- a/docs/format.html.in
+++ /dev/null
@@ -1,48 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>XML Format</h1>
-
-
- <p>
- Objects in the libvirt API are configured using XML documents to allow
- for ease of extension in future releases. Each XML document has an
- associated Relax-NG schema that can be used to validate documents
- prior to usage.
- </p>
-
-
- <ul>
- <li><a href="formatdomain.html">Domains</a></li>
- <li><a
href="formatnetwork.html">Networks</a></li>
- <li><a href="formatnwfilter.html">Network
filtering</a></li>
- <li><a href="formatnetworkport.html">Network
ports</a></li>
- <li><a
href="formatstorage.html">Storage</a></li>
- <li><a href="formatstorageencryption.html">Storage
encryption</a></li>
- <li><a
href="formatcaps.html">Capabilities</a></li>
- <li><a href="formatdomaincaps.html">Domain
capabilities</a></li>
- <li><a href="formatstoragecaps.html">Storage Pool
capabilities</a></li>
- <li><a href="formatnode.html">Node
devices</a></li>
- <li><a href="formatsecret.html">Secrets</a></li>
- <li><a
href="formatsnapshot.html">Snapshots</a></li>
- <li><a
href="formatcheckpoint.html">Checkpoints</a></li>
- <li><a href="formatbackup.html">Backup
jobs</a></li>
- </ul>
-
- <h2>Command line validation</h2>
-
- <p>
- The <code>virt-xml-validate</code> tool provides a simple command line
- for validating XML documents prior to giving them to libvirt. It uses
- the locally installed RNG schema documents. It will auto-detect which
- schema to use for validation based on the name of the top level element
- in the input document. Thus it merely requires the XML document filename
- to be passed on the command line
- </p>
-
- <pre>
-$ virt-xml-validate /path/to/XML/file</pre>
-
- </body>
-</html>
diff --git a/docs/format.rst b/docs/format.rst
new file mode 100644
index 0000000000..a261007e73
--- /dev/null
+++ b/docs/format.rst
@@ -0,0 +1,35 @@
+==========
+XML Format
+==========
+
+Objects in the libvirt API are configured using XML documents to allow for ease
+of extension in future releases. Each XML document has an associated Relax-NG
+schema that can be used to validate documents prior to usage.
+
+- `Domains <formatdomain.html>`__
+- `Networks <formatnetwork.html>`__
+- `Network filtering <formatnwfilter.html>`__
+- `Network ports <formatnetworkport.html>`__
+- `Storage <formatstorage.html>`__
+- `Storage encryption <formatstorageencryption.html>`__
+- `Capabilities <formatcaps.html>`__
+- `Domain capabilities <formatdomaincaps.html>`__
+- `Storage Pool capabilities <formatstoragecaps.html>`__
+- `Node devices <formatnode.html>`__
+- `Secrets <formatsecret.html>`__
+- `Snapshots <formatsnapshot.html>`__
+- `Checkpoints <formatcheckpoint.html>`__
+- `Backup jobs <formatbackup.html>`__
+
+Command line validation
+-----------------------
+
+The ``virt-xml-validate`` tool provides a simple command line for validating XML
+documents prior to giving them to libvirt. It uses the locally installed RNG
+schema documents. It will auto-detect which schema to use for validation based
+on the name of the top level element in the input document. Thus it merely
+requires the XML document filename to be passed on the command line
+
+::
+
+ $ virt-xml-validate /path/to/XML/file
diff --git a/docs/meson.build b/docs/meson.build
index aa8bad89f0..acc455c7c7 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'format',
'formatcaps',
'formatdomaincaps',
'formatnetwork',
@@ -82,6 +81,7 @@ docs_rst_files = [
'drvxen',
'errors',
'firewall',
+ 'format',
'formatbackup',
'formatcheckpoint',
'formatdomain',
--
2.35.1
7:10 a.m.
New subject: [PATCH 17/29] docs: Convert 'formatcaps' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatcaps.html.in | 219 ----------------------------------------
docs/formatcaps.rst | 196 +++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 197 insertions(+), 220 deletions(-)
delete mode 100644 docs/formatcaps.html.in
create mode 100644 docs/formatcaps.rst
diff --git a/docs/formatcaps.html.in b/docs/formatcaps.html.in
deleted file mode 100644
index 09662f78c8..0000000000
--- a/docs/formatcaps.html.in
+++ /dev/null
@@ -1,219 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Driver capabilities XML format</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="elements">Element and attribute
overview</a></h2>
-
- <p>As new virtualization engine support gets added to libvirt, and to
- handle cases like QEMU supporting a variety of emulations, a query
- interface has been added in 0.2.1 allowing to list the set of supported
- virtualization capabilities on the host:</p>
-
- <pre>char * virConnectGetCapabilities (virConnectPtr conn);</pre>
-
- <p>The value returned is an XML document listing the virtualization
- capabilities of the host and virtualization engine to which
- <code>@conn</code> is connected. One can test it using
<code>virsh</code>
- command line tool command '<code>capabilities</code>', it dumps
the XML
- associated to the current connection. </p>
-
- <p>As can be seen in the <a
href="#elementExamples">example</a>, the
- capabilities XML consists of the <code>capabilities</code> element which
- have exactly one <code>host</code> child element to report information
on
- host capabilities, and zero or more <code>guest</code> element to
express
- the set of architectures the host can run at the moment.</p>
-
-
- <h3><a id="elementHost">Host capabilities</a></h3>
-
- <p>The <code><host/></code> element consists of the
following child
- elements:</p>
- <dl>
- <dt><code>uuid</code></dt>
- <dd>The host UUID.</dd>
-
- <dt><code>cpu</code></dt>
- <dd>The host CPU architecture and features.</dd>
-
- <dt><code>power_management</code></dt>
- <dd>whether host is capable of memory suspend, disk hibernation, or
- hybrid suspend.</dd>
-
- <dt><code>migration_features</code></dt>
- <dd>This element exposes information on the hypervisor's migration
- capabilities, like live migration, supported URI transports, and so
- on.</dd>
-
- <dt><code>topology</code></dt>
- <dd>This element embodies the host internal topology. Management
- applications may want to learn this information when orchestrating new
- guests - e.g. due to reduce inter-NUMA node transfers.</dd>
-
- <dt><code>secmodel</code></dt>
- <dd>To find out default security labels for different security models you
- need to parse this element. In contrast with the former elements, this is
- repeated for each security model the libvirt daemon currently supports.
- </dd>
- </dl>
-
-
- <h3><a id="elementGuest">Guest
capabilities</a></h3>
-
- <p>While the <a href="#elementHost">previous section</a>
aims at host
- capabilities, this one focuses on capabilities available to a guest
- using a given hypervisor. The <code><guest/></code> element
will
- typically wrap up the following elements:</p>
-
- <dl>
- <dt><code>os_type</code></dt>
- <dd>This expresses what kind of operating system the hypervisor
- is able to run. Possible values are:
- <dl>
- <dt><code>xen</code></dt>
- <dd>for XEN PV</dd>
-
- <dt><code>linux</code></dt>
- <dd>legacy alias for <code>xen</code></dd>
-
- <dt><code>xenpvh</code></dt>
- <dd>for XEN PVH</dd>
-
- <dt><code>hvm</code></dt>
- <dd>Unmodified operating system</dd>
-
- <dt><code>exe</code></dt>
- <dd>Container based virtualization</dd>
- </dl>
- </dd>
-
- <dt><code>arch</code></dt>
- <dd>This element brings some information on supported guest
- architecture. Possible subelements are:
- <dl>
- <dt><code>wordsize</code></dt><dd>Size of CPU
word in bits, for example 64.</dd>
- <dt><code>emulator</code></dt><dd>Emulator
(device model) path, for
- use in <a
href="formatdomain.html#elementEmulator">emulator</a>
- element of domain XML.</dd>
- <dt><code>loader</code></dt><dd>Loader path,
for use in
- <a href="formatdomain.html#elementLoader">loader</a>
element of domain
- XML.</dd>
- <dt><code>machine</code></dt><dd>Machine type,
for use in
- <a
href="formatdomain.html#attributeOSTypeMachine">machine</a>
- attribute of os/type element in domain XML. For example Xen
- supports <code>xenfv</code> for HVM,
<code>xenpv</code> for
- PV, or <code>xenpvh</code> for PVH.</dd>
- <dt><code>domain</code></dt><dd>The
<code>type</code> attribute of
- this element specifies the type of hypervisor required to run the
- domain. Use in <a
href="formatdomain.html#attributeDomainType">type</a>
- attribute of the domain root element.</dd>
- </dl>
- </dd>
-
- <dt><code>features</code></dt>
- <dd>This optional element encases possible features that can be used
- with a guest of described type. Possible subelements are:
- <dl>
- <dt><code>pae</code></dt><dd>If present, 32-bit
guests can use PAE
- address space extensions, <span class="since">since
- 0.4.1</span></dd>
- <dt><code>nonpae</code></dt><dd>If present,
32-bit guests can be run
- without requiring PAE, <span class="since">since
- 0.4.1</span></dd>
- <dt><code>ia64_be</code></dt><dd>If present,
IA64 guests can be run in
- big-endian mode, <span class="since">since
0.4.1</span></dd>
- <dt><code>acpi</code></dt><dd>If this element
is present,
- the <code>default</code> attribute describes whether the
- hypervisor exposes ACPI to the guest by default, and
- the <code>toggle</code> attribute describes whether the
- user can override this
- default. <span class="since">Since
0.4.1</span></dd>
- <dt><code>apic</code></dt><dd>If this element
is present,
- the <code>default</code> attribute describes whether the
- hypervisor exposes APIC to the guest by default, and
- the <code>toggle</code> attribute describes whether the
- user can override this
- default. <span class="since">Since
0.4.1</span></dd>
- <dt><code>cpuselection</code></dt><dd>If this
element is present, the
- hypervisor supports the <code><cpu></code>
element
- within a domain definition for fine-grained control over
- the CPU presented to the
- guest. <span class="since">Since
0.7.5</span></dd>
- <dt><code>deviceboot</code></dt><dd>If this
element is present,
- the <code><boot order='...'/></code>
element can
- be used inside devices, rather than the older boot
- specification by category. <span class="since">Since
- 0.8.8</span></dd>
- <dt><code>disksnapshot</code></dt><dd>If this
element is present,
- the <code>default</code> attribute describes whether
- external disk snapshots are supported. If absent,
- external snapshots may still be supported, but it
- requires attempting the API and checking for an error to
- find out for sure. <span class="since">Since
- 1.2.3</span></dd>
- </dl>
- </dd>
- </dl>
-
- <h3><a id="elementExamples">Examples</a></h3>
-
- <p>For example, in the case of a 64-bit machine with hardware
- virtualization capabilities enabled in the chip and
- BIOS you will see:</p>
-
- <pre><capabilities>
- <span style="color: #E50000"><host>
- <cpu>
- <arch>x86_64</arch>
- <features>
- <vmx/>
- </features>
- <model>core2duo</model>
- <vendor>Intel</vendor>
- <topology sockets="1" dies="1" cores="2"
threads="1"/>
- <feature name="lahf_lm"/>
- <feature name='xtpr'/>
- ...
- </cpu>
- <power_management>
- <suspend_mem/>
- <suspend_disk/>
- <suspend_hybrid/>
- </power_management>
- </host></span>
-
- <!-- xen-3.0-x86_64 -->
- <span style="color: #0000E5"><guest>
- <os_type>xen</os_type>
- <arch name="x86_64">
- <wordsize>64</wordsize>
- <domain type="xen"></domain>
- <emulator>/usr/lib64/xen/bin/qemu-dm</emulator>
- </arch>
- <features>
- </features>
- </guest></span>
-
- <!-- hvm-3.0-x86_32 -->
- <span style="color: #00B200"><guest>
- <os_type>hvm</os_type>
- <arch name="i686">
- <wordsize>32</wordsize>
- <domain type="xen"></domain>
- <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
- <machine>pc</machine>
- <machine>isapc</machine>
- <loader>/usr/lib/xen/boot/hvmloader</loader>
- </arch>
- <features>
- <cpuselection/>
- <deviceboot/>
- </features>
- </guest></span>
- ...
-</capabilities></pre>
- </body>
-</html>
diff --git a/docs/formatcaps.rst b/docs/formatcaps.rst
new file mode 100644
index 0000000000..1ba847cea1
--- /dev/null
+++ b/docs/formatcaps.rst
@@ -0,0 +1,196 @@
+.. role:: since
+
+==============================
+Driver capabilities XML format
+==============================
+
+.. contents::
+
+Element and attribute overview
+------------------------------
+
+As new virtualization engine support gets added to libvirt, and to handle cases
+like QEMU supporting a variety of emulations, a query interface has been added
+in 0.2.1 allowing to list the set of supported virtualization capabilities on
+the host:
+
+::
+
+ char * virConnectGetCapabilities (virConnectPtr conn);
+
+The value returned is an XML document listing the virtualization capabilities of
+the host and virtualization engine to which ``@conn`` is connected. One can test
+it using ``virsh`` command line tool command '``capabilities``', it dumps the
+XML associated to the current connection.
+
+As can be seen in the `example <#elementExamples>`__, the capabilities XML
+consists of the ``capabilities`` element which have exactly one ``host`` child
+element to report information on host capabilities, and zero or more ``guest``
+element to express the set of architectures the host can run at the moment.
+
+Host capabilities
+~~~~~~~~~~~~~~~~~
+
+The ``<host/>`` element consists of the following child elements:
+
+``uuid``
+ The host UUID.
+``cpu``
+ The host CPU architecture and features.
+``power_management``
+ whether host is capable of memory suspend, disk hibernation, or hybrid
+ suspend.
+``migration_features``
+ This element exposes information on the hypervisor's migration capabilities,
+ like live migration, supported URI transports, and so on.
+``topology``
+ This element embodies the host internal topology. Management applications may
+ want to learn this information when orchestrating new guests - e.g. due to
+ reduce inter-NUMA node transfers.
+``secmodel``
+ To find out default security labels for different security models you need to
+ parse this element. In contrast with the former elements, this is repeated
+ for each security model the libvirt daemon currently supports.
+
+Guest capabilities
+~~~~~~~~~~~~~~~~~~
+
+While the `previous section <#elementHost>`__ aims at host capabilities, this
+one focuses on capabilities available to a guest using a given hypervisor. The
+``<guest/>`` element will typically wrap up the following elements:
+
+``os_type``
+ This expresses what kind of operating system the hypervisor is able to run.
+ Possible values are:
+
+ ``xen``
+ for XEN PV
+ ``linux``
+ legacy alias for ``xen``
+ ``xenpvh``
+ for XEN PVH
+ ``hvm``
+ Unmodified operating system
+ ``exe``
+ Container based virtualization
+``arch``
+ This element brings some information on supported guest architecture.
+ Possible subelements are:
+
+ ``wordsize``
+ Size of CPU word in bits, for example 64.
+ ``emulator``
+ Emulator (device model) path, for use in
+ `emulator <formatdomain.html#elementEmulator>`__ element of domain XML.
+ ``loader``
+ Loader path, for use in `loader <formatdomain.html#elementLoader>`__
+ element of domain XML.
+ ``machine``
+ Machine type, for use in
+ `machine <formatdomain.html#attributeOSTypeMachine>`__ attribute of
+ os/type element in domain XML. For example Xen supports ``xenfv`` for HVM,
+ ``xenpv`` for PV, or ``xenpvh`` for PVH.
+ ``domain``
+ The ``type`` attribute of this element specifies the type of hypervisor
+ required to run the domain. Use in
+ `type <formatdomain.html#attributeDomainType>`__ attribute of the domain
+ root element.
+``features``
+ This optional element encases possible features that can be used with a guest
+ of described type. Possible subelements are:
+
+ ``pae``
+ If present, 32-bit guests can use PAE address space extensions,
+ :since:`since 0.4.1`
+ ``nonpae``
+ If present, 32-bit guests can be run without requiring PAE, :since:`since
+ 0.4.1`
+ ``ia64_be``
+ If present, IA64 guests can be run in big-endian mode, :since:`since
+ 0.4.1`
+ ``acpi``
+ If this element is present, the ``default`` attribute describes whether
+ the hypervisor exposes ACPI to the guest by default, and the ``toggle``
+ attribute describes whether the user can override this default.
+ :since:`Since 0.4.1`
+ ``apic``
+ If this element is present, the ``default`` attribute describes whether
+ the hypervisor exposes APIC to the guest by default, and the ``toggle``
+ attribute describes whether the user can override this default.
+ :since:`Since 0.4.1`
+ ``cpuselection``
+ If this element is present, the hypervisor supports the ``<cpu>`` element
+ within a domain definition for fine-grained control over the CPU presented
+ to the guest. :since:`Since 0.7.5`
+ ``deviceboot``
+ If this element is present, the ``<boot order='...'/>`` element can
be
+ used inside devices, rather than the older boot specification by category.
+ :since:`Since 0.8.8`
+ ``disksnapshot``
+ If this element is present, the ``default`` attribute describes whether
+ external disk snapshots are supported. If absent, external snapshots may
+ still be supported, but it requires attempting the API and checking for an
+ error to find out for sure. :since:`Since 1.2.3`
+
+Examples
+~~~~~~~~
+
+For example, in the case of a 64-bit machine with hardware virtualization
+capabilities enabled in the chip and BIOS you will see:
+
+::
+
+ <capabilities>
+ <host>
+ <cpu>
+ <arch>x86_64</arch>
+ <features>
+ <vmx/>
+ </features>
+ <model>core2duo</model>
+ <vendor>Intel</vendor>
+ <topology sockets="1" dies="1" cores="2"
threads="1"/>
+ <feature name="lahf_lm"/>
+ <feature name='xtpr'/>
+ ...
+ </cpu>
+ <power_management>
+ <suspend_mem/>
+ <suspend_disk/>
+ <suspend_hybrid/>
+ </power_management>
+ </host>
+
+
+ <!-- xen-3.0-x86_64 -->
+ <guest>
+ <os_type>xen</os_type>
+ <arch name="x86_64">
+ <wordsize>64</wordsize>
+ <domain type="xen"></domain>
+ <emulator>/usr/lib64/xen/bin/qemu-dm</emulator>
+ </arch>
+ <features>
+ </features>
+ </guest>
+
+
+ <!-- hvm-3.0-x86_32 -->
+ <guest>
+ <os_type>hvm</os_type>
+ <arch name="i686">
+ <wordsize>32</wordsize>
+ <domain type="xen"></domain>
+ <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
+ <machine>pc</machine>
+ <machine>isapc</machine>
+ <loader>/usr/lib/xen/boot/hvmloader</loader>
+ </arch>
+ <features>
+ <cpuselection/>
+ <deviceboot/>
+ </features>
+ </guest>
+
+ ...
+ </capabilities>
diff --git a/docs/meson.build b/docs/meson.build
index acc455c7c7..95c9babcf5 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'formatcaps',
'formatdomaincaps',
'formatnetwork',
'formatnetworkport',
@@ -83,6 +82,7 @@ docs_rst_files = [
'firewall',
'format',
'formatbackup',
+ 'formatcaps',
'formatcheckpoint',
'formatdomain',
'formatsecret',
--
2.35.1
6:39 a.m.
New subject: [PATCH 17/29] docs: Convert 'formatcaps' page to rST
On Mon, Mar 28, 2022 at 14:10:32 +0200, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatcaps.html.in | 219 ----------------------------------------
docs/formatcaps.rst | 196 +++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 197 insertions(+), 220 deletions(-)
delete mode 100644 docs/formatcaps.html.in
create mode 100644 docs/formatcaps.rst
There was a modification in the html.in file now, so I'll drop this
patch from the series and re-convert it later in another pass.
7:10 a.m.
New subject: [PATCH 18/29] docs: Convert 'formatdomaincaps' to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatdomain.rst | 20 +-
docs/formatdomaincaps.html.in | 693 ----------------------------------
docs/formatdomaincaps.rst | 602 +++++++++++++++++++++++++++++
docs/kbase/backing_chains.rst | 2 +-
docs/meson.build | 2 +-
5 files changed, 614 insertions(+), 705 deletions(-)
delete mode 100644 docs/formatdomaincaps.html.in
create mode 100644 docs/formatdomaincaps.rst
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 95ace2677e..2dc52baa14 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -1406,15 +1406,15 @@ In case no restrictions need to be put on CPU model and its
features, a simpler
expected. :since:`Since 3.2.0 and QEMU 2.9.0` this mode works the way it
was designed and it is indicated by the ``fallback`` attribute set to
``forbid`` in the host-model CPU definition advertised in `domain
- capabilities XML <formatdomaincaps.html#elementsCPU>`__. When ``fallback``
- attribute is set to ``allow`` in the domain capabilities XML, it is
- recommended to use ``custom`` mode with just the CPU model from the host
- capabilities XML. :since:`Since 1.2.11` PowerISA allows processors to run
- VMs in binary compatibility mode supporting an older version of ISA.
- Libvirt on PowerPC architecture uses the ``host-model`` to signify a guest
- mode CPU running in binary compatibility mode. Example: When a user needs
- a power7 VM to run in compatibility mode on a Power8 host, this can be
- described in XML as follows :
+ capabilities XML <formatdomaincaps.html#cpu-configuration>`__. When
+ ``fallback`` attribute is set to ``allow`` in the domain capabilities
+ XML, it is recommended to use ``custom`` mode with just the CPU model
+ from the host capabilities XML. :since:`Since 1.2.11` PowerISA allows
+ processors to run VMs in binary compatibility mode supporting an older
+ version of ISA. Libvirt on PowerPC architecture uses the ``host-model``
+ to signify a guest mode CPU running in binary compatibility mode.
+ Example: When a user needs a power7 VM to run in compatibility mode on a
+ Power8 host, this can be described in XML as follows :
::
@@ -2902,7 +2902,7 @@ paravirtualized driver is specified via the ``disk`` element.
This element describes the backing store used by the disk specified by
sibling ``source`` element. :since:`Since 1.2.4.` If the hypervisor driver
does not support the
- `backingStoreInput <formatdomaincaps.html#featureBackingStoreInput>`__ (
+ `backingStoreInput <formatdomaincaps.html#backingstoreinput>`__ (
:since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on
input and only used for output to describe the detected backing chains of
running domains. If ``backingStoreInput`` is supported the ``backingStore``
diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in
deleted file mode 100644
index 35b8bf3def..0000000000
--- a/docs/formatdomaincaps.html.in
+++ /dev/null
@@ -1,693 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Domain capabilities XML format</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="Overview">Overview</a></h2>
-
- <p>Sometimes, when a new domain is to be created it may come handy to know
- the capabilities of the hypervisor so the correct combination of devices and
- drivers is used. For example, when management application is considering the
- mode for a host device's passthrough there are several options depending not
- only on host, but on hypervisor in question too. If the hypervisor is qemu
- then it needs to be more recent to support VFIO, while legacy KVM is
- achievable just fine with older qemus.</p>
-
- <p>The main difference between
- <a
href="/html/libvirt-libvirt-host.html#virConnectGetCapabilities">
- <code>virConnectGetCapabilities</code>
- </a>
- and the emulator capabilities API is, the former one aims more on
- the host capabilities (e.g. NUMA topology, security models in
- effect, etc.) while the latter one specializes on the hypervisor
- capabilities.</p>
-
- <p>While the <a href="formatcaps.html">Driver
Capabilities</a> provides the
- host capabilities (e.g NUMA topology, security models in effect, etc.), the
- Domain Capabilities provides the hypervisor specific capabilities for
- Management Applications to query and make decisions regarding what to
- utilize.</p>
-
- <p>The Domain Capabilities can provide information such as the correct
- combination of devices and drivers that are supported. Knowing which host
- and hypervisor specific options are available or supported would allow the
- management application to choose an appropriate mode for a pass-through
- host device as well as which adapter to utilize.</p>
-
- <p>Some XML elements may be entirely omitted from the domaincapabilities
- XML, depending on what the libvirt driver has filled in. Applications
- should only act on what is explicitly reported in the domaincapabilities
- XML. For example, if <disk supported='yes'/> is present, you
can safely
- assume the driver supports <disk> devices. If <disk
supported='no'/> is
- present, you can safely assume the driver does NOT support <disk>
- devices. If the <disk> block is omitted entirely, the driver is not
- indicating one way or the other whether it supports <disk> devices,
and
- applications should not interpret the missing block to mean any thing in
- particular.</p>
-
- <h2><a id="elements">Element and attribute
overview</a></h2>
-
- <p> A new query interface was added to the virConnect API's to retrieve
the
- XML listing of the set of domain capabilities (<span
class="since">Since
- 1.2.7</span>):</p>
-
-<pre>
-<a
href="/html/libvirt-libvirt-domain.html#virConnectGetDomainCapabilities">virConnectGetDomainCapabilities</a>
-</pre>
-
- <p>The root element that emulator capability XML document starts with has
- name <code>domainCapabilities</code>. It contains at least four direct
- child elements:</p>
-
-<pre>
-<domainCapabilities>
- <path>/usr/bin/qemu-system-x86_64</path>
- <domain>kvm</domain>
- <machine>pc-i440fx-2.1</machine>
- <arch>x86_64</arch>
- ...
-</domainCapabilities>
-</pre>
- <dl>
- <dt><code>path</code></dt>
- <dd>The full path to the emulator binary.</dd>
-
- <dt><code>domain</code></dt>
- <dd>Describes the <a
href="formatdomain.html#elements">virtualization
- type</a> (or so called domain type).</dd>
-
- <dt><code>machine</code></dt>
- <dd>The domain's <a
href="formatdomain.html#elementsOSBIOS">machine
- type</a>. Since not every hypervisor has a sense of machine types
- this element might be omitted in such drivers.</dd>
-
- <dt><code>arch</code></dt>
- <dd>The domain's <a
href="formatdomain.html#elementsOSBIOS">
- architecture</a>.</dd>
-
- </dl>
-
- <h3><a id="elementsCPUAllocation">CPU
Allocation</a></h3>
-
- <p>Before any devices capability occurs, there might be info on domain
- wide capabilities, e.g. virtual CPUs:</p>
-
-<pre>
-<domainCapabilities>
- ...
- <vcpu max='255'/>
- ...
-</domainCapabilities>
-</pre>
-
- <dl>
- <dt><code>vcpu</code></dt>
- <dd>The maximum number of supported virtual CPUs</dd>
- </dl>
-
- <h3><a id="elementsOSBIOS">BIOS
bootloader</a></h3>
-
- <p>Sometimes users might want to tweak some BIOS knobs or use
- UEFI. For cases like that, <a
-
href="formatdomain.html#elementsOSBIOS"><code>os</code></a>
- element exposes what values can be passed to its children.</p>
-
-<pre>
-<domainCapabilities>
- ...
- <os supported='yes'>
- <enum name='firmware'>
- <value>bios</value>
- <value>efi</value>
- </enum>
- <loader supported='yes'>
- <value>/usr/share/OVMF/OVMF_CODE.fd</value>
- <enum name='type'>
- <value>rom</value>
- <value>pflash</value>
- </enum>
- <enum name='readonly'>
- <value>yes</value>
- <value>no</value>
- </enum>
- <enum name='secure'>
- <value>yes</value>
- <value>no</value>
- </enum>
- </loader>
- </os>
- ...
-<domainCapabilities>
-</pre>
-
- <p>The <code>firmware</code> enum corresponds to the
- <code>firmware</code> attribute of the <code>os</code>
element in
- the domain XML. The presence of this enum means libvirt is capable
- of the so-called firmware auto-selection feature. And the listed
- firmware values represent the accepted input in the domain
- XML. Note that the <code>firmware</code> enum reports only those
- values for which a firmware "descriptor file" exists on the host.
- Firmware descriptor file is a small JSON document that describes
- details about a given BIOS or UEFI binary on the host, e.g. the
- firmware binary path, its architecture, supported machine types,
- NVRAM template, etc. This ensures that the reported values won't
- cause a failure on guest boot.
- </p>
-
- <p>For the <code>loader</code> element, the following can
occur:</p>
-
- <dl>
- <dt><code>value</code></dt>
- <dd>List of known firmware binary paths. Currently this is used
- only to advertise the known location of OVMF binaries for
- QEMU. OVMF binaries will only be listed if they actually exist on
- host.</dd>
-
- <dt><code>type</code></dt>
- <dd>Whether the boot loader is a typical BIOS (<code>rom</code>)
- or a UEFI firmware (<code>pflash</code>). Each
<code>value</code>
- sub-element under the <code>type</code> enum represents a possible
- value for the <code>type</code> attribute for the
<loader/>
- element in the domain XML. E.g. the presence
- of <code>pfalsh</code> under the <code>type</code> enum
means that
- a domain XML can use UEFI firmware via: <loader/>
- type="pflash"
...>/path/to/the/firmware/binary/</loader>.
- </dd>
-
- <dt><code>readonly</code></dt>
- <dd>Options for the <code>readonly</code> attribute of the
- <loader/> element in the domain XML.</dd>
-
- <dt><code>secure</code></dt>
- <dd>Options for the <code>secure</code> attribute of the
- <loader/> element in the domain XML. Note that the
- value <code>yes</code> is listed only if libvirt detects a
- firmware descriptor file that has path to an OVMF binary that
- supports Secure boot, and lists its architecture and supported
- machine type.</dd>
- </dl>
-
- <h3><a id="elementsCPU">CPU configuration</a></h3>
-
- <p>
- The <code>cpu</code> element exposes options usable for configuring
- <a href="formatdomain.html#elementsCPU">guest CPUs</a>.
- </p>
-
-<pre>
-<domainCapabilities>
- ...
- <cpu>
- <mode name='host-passthrough' supported='yes'>
- <enum name='hostPassthroughMigratable'>
- <value>on</value>
- <value>off</value>
- </enum>
- </mode>
- <mode name='maximum' supported='yes'>
- <enum name='maximumMigratable'>
- <value>on</value>
- <value>off</value>
- </enum>
- </mode>
- <mode name='host-model' supported='yes'>
- <model fallback='allow'>Broadwell</model>
- <vendor>Intel</vendor>
- <feature policy='disable' name='aes'/>
- <feature policy='require' name='vmx'/>
- </mode>
- <mode name='custom' supported='yes'>
- <model usable='no'
deprecated='no'>Broadwell</model>
- <model usable='yes'
deprecated='no'>Broadwell-noTSX</model>
- <model usable='no'
deprecated='yes'>Haswell</model>
- ...
- </mode>
- </cpu>
- ...
-<domainCapabilities>
-</pre>
-
- <p>
- Each CPU mode understood by libvirt is described with a
- <code>mode</code> element which tells whether the particular mode
- is supported and provides (when applicable) more details about it:
- </p>
-
- <dl>
- <dt><code>host-passthrough</code></dt>
- <dd>
- The <code>hostPassthroughMigratable</code> enum shows possible
values
- of the <code>migratable</code> attribute for the <cpu>
element
- with <code>mode='host-passthrough'</code> in the domain XML.
- </dd>
-
- <dt><code>host-model</code></dt>
- <dd>
- If <code>host-model</code> is supported by the hypervisor, the
- <code>mode</code> describes the guest CPU which will be used when
- starting a domain with <code>host-model</code> CPU. The hypervisor
- specifics (such as unsupported CPU models or features, machine type,
- etc.) may be accounted for in this guest CPU specification and thus
- the CPU can be different from the one shown in host capabilities XML.
- This is indicated by the <code>fallback</code> attribute of the
- <code>model</code> sub element: <code>allow</code> means
not all
- specifics were accounted for and thus the CPU a guest will see may
- be different; <code>forbid</code> indicates that the CPU a guest
will
- see should match this CPU definition.
- </dd>
-
- <dt><code>custom</code></dt>
- <dd>
- The <code>mode</code> element contains a list of supported CPU
- models, each described by a dedicated <code>model</code> element.
- The <code>usable</code> attribute specifies whether the model can
- be used directly on the host. When usable='no' the corresponding model
- cannot be used without disabling some features that the CPU of such
- model is expected to have. A special value <code>unknown</code>
- indicates libvirt does not have enough information to provide the
- usability data. The <code>deprecated</code> attribute reflects
- the hypervisor's policy on usage of this model
- <span class="since">(since 7.1.0)</span>.
- </dd>
- </dl>
-
- <h3><a id="elementsIothreads">I/O Threads</a></h3>
-
- <p>
- The <code>iothread</code> elements indicates whether or not
- <a href="formatdomain.html#elementsIOThreadsAllocation">I/O
threads</a>
- are supported.
- </p>
-
-<pre>
-<domainCapabilities>
- ...
- <iothread supported='yes'/>
- ...
-<domainCapabilities>
-</pre>
-
- <h3><a id="elementsMemoryBacking">Memory
Backing</a></h3>
-
- <p>
- The <code>memory backing</code> element indicates whether or not
- <a href="formatdomain.html#memory-backing">memory
backing</a>
- is supported.
- </p>
-
-<pre>
-<domainCapabilities>
- ...
- <memoryBacking supported='yes'>
- <enum name='sourceType'>
- <value>anonymous</value>
- <value>file</value>
- <value>memfd</value>
- </enum>
- </memoryBacking>
- ...
-<domainCapabilities>
-</pre>
-
- <dl>
- <dt><code>sourceType</code></dt>
- <dd>Options for the <code>type</code> attribute of the
- <memoryBacking><source> element.</dd>
- </dl>
-
- <h3><a id="elementsDevices">Devices</a></h3>
-
- <p>
- Another set of XML elements describe the supported devices and their
- capabilities. All devices occur as children of the main
- <code>devices</code> element.
- </p>
-
-<pre>
-<domainCapabilities>
- ...
- <devices>
- <disk supported='yes'>
- <enum name='diskDevice'>
- <value>disk</value>
- <value>cdrom</value>
- <value>floppy</value>
- <value>lun</value>
- </enum>
- ...
- </disk>
- <hostdev supported='no'/>
- </devices>
-</domainCapabilities>
-</pre>
-
- <p>Reported capabilities are expressed as an enumerated list of available
- options for each of the element or attribute. For example, the
- <disk/> element has an attribute <code>device</code> which
can
- support the values <code>disk</code>, <code>cdrom</code>,
- <code>floppy</code>, or <code>lun</code>.</p>
-
- <h4><a id="elementsDisks">Hard drives, floppy disks,
CDROMs</a></h4>
- <p>Disk capabilities are exposed under the <code>disk</code>
element. For
- instance:</p>
-
-<pre>
-<domainCapabilities>
- ...
- <devices>
- <disk supported='yes'>
- <enum name='diskDevice'>
- <value>disk</value>
- <value>cdrom</value>
- <value>floppy</value>
- <value>lun</value>
- </enum>
- <enum name='bus'>
- <value>ide</value>
- <value>fdc</value>
- <value>scsi</value>
- <value>virtio</value>
- <value>xen</value>
- <value>usb</value>
- <value>sata</value>
- <value>sd</value>
- </enum>
- </disk>
- ...
- </devices>
-</domainCapabilities>
-</pre>
-
- <dl>
- <dt><code>diskDevice</code></dt>
- <dd>Options for the <code>device</code> attribute of the
<disk/>
- element.</dd>
-
- <dt><code>bus</code></dt>
- <dd>Options for the <code>bus</code> attribute of the
<target/>
- element for a <disk/>.</dd>
- </dl>
-
-
- <h4><a id="elementsGraphics">Graphical
framebuffers</a></h4>
- <p>Graphics device capabilities are exposed under the
- <code>graphics</code> element. For instance:</p>
-
-<pre>
-<domainCapabilities>
- ...
- <devices>
- <graphics supported='yes'>
- <enum name='type'>
- <value>sdl</value>
- <value>vnc</value>
- <value>spice</value>
- </enum>
- </graphics>
- ...
- </devices>
-</domainCapabilities>
-</pre>
-
- <dl>
- <dt><code>type</code></dt>
- <dd>Options for the <code>type</code> attribute of the
<graphics/>
- element.</dd>
- </dl>
-
-
- <h4><a id="elementsVideo">Video device</a></h4>
- <p>Video device capabilities are exposed under the
- <code>video</code> element. For instance:</p>
-
-<pre>
-<domainCapabilities>
- ...
- <devices>
- <video supported='yes'>
- <enum name='modelType'>
- <value>vga</value>
- <value>cirrus</value>
- <value>vmvga</value>
- <value>qxl</value>
- <value>virtio</value>
- </enum>
- </video>
- ...
- </devices>
-</domainCapabilities>
-</pre>
-
- <dl>
- <dt><code>modelType</code></dt>
- <dd>Options for the <code>type</code> attribute of the
- <video><model> element.</dd>
- </dl>
-
-
- <h4><a id="elementsHostDev">Host device
assignment</a></h4>
- <p>Some host devices can be passed through to a guest (e.g. USB, PCI and
- SCSI). Well, only if the following is enabled:</p>
-
-<pre>
-<domainCapabilities>
- ...
- <devices>
- <hostdev supported='yes'>
- <enum name='mode'>
- <value>subsystem</value>
- <value>capabilities</value>
- </enum>
- <enum name='startupPolicy'>
- <value>default</value>
- <value>mandatory</value>
- <value>requisite</value>
- <value>optional</value>
- </enum>
- <enum name='subsysType'>
- <value>usb</value>
- <value>pci</value>
- <value>scsi</value>
- </enum>
- <enum name='capsType'>
- <value>storage</value>
- <value>misc</value>
- <value>net</value>
- </enum>
- <enum name='pciBackend'>
- <value>default</value>
- <value>kvm</value>
- <value>vfio</value>
- <value>xen</value>
- </enum>
- </hostdev>
- </devices>
-</domainCapabilities>
-</pre>
-
- <dl>
- <dt><code>mode</code></dt>
- <dd>Options for the <code>mode</code> attribute of the
<hostdev/>
- element.</dd>
-
- <dt><code>startupPolicy</code></dt>
- <dd>Options for the <code>startupPolicy</code> attribute of the
- <hostdev/> element.</dd>
-
- <dt><code>subsysType</code></dt>
- <dd>Options for the <code>type</code> attribute of the
<hostdev/>
- element in case of <code>mode="subsystem"</code>.</dd>
-
- <dt><code>capsType</code></dt>
- <dd>Options for the <code>type</code> attribute of the
<hostdev/>
- element in case of
<code>mode="capabilities"</code>.</dd>
-
- <dt><code>pciBackend</code></dt>
- <dd>Options for the <code>name</code> attribute of the
<driver/>
- element.</dd>
- </dl>
-
-
- <h4><a id="elementsRNG">RNG device</a></h4>
- <p>RNG device capabilities are exposed under the
- <code>rng</code> element. For instance:</p>
-
-<pre>
-<domainCapabilities>
- ...
- <devices>
- <rng supported='yes'>
- <enum name='model'>
- <value>virtio</value>
- <value>virtio-transitional</value>
- <value>virtio-non-transitional</value>
- </enum>
- <enum name='backendModel'>
- <value>random</value>
- <value>egd</value>
- <value>builtin</value>
- </enum>
- </rng>
- ...
- </devices>
-</domainCapabilities>
-</pre>
-
- <dl>
- <dt><code>model</code></dt>
- <dd>Options for the <code>model</code> attribute of the
- <rng> element.</dd>
- <dt><code>backendModel</code></dt>
- <dd>Options for the <code>model</code> attribute of the
- <rng><backend> element.</dd>
- </dl>
-
-
- <h4><a id="elementsFilesystem">Filesystem
device</a></h4>
- <p>Filesystem device capabilities are exposed under the
- <code>filesystem</code> element. For instance:</p>
-
-<pre>
-<domainCapabilities>
- ...
- <devices>
- <filesystem supported='yes'>
- <enum name='driverType'>
- <value>default</value>
- <value>path</value>
- <value>handle</value>
- <value>virtiofs</value>
- </enum>
- </filesystem>
- ...
- </devices>
-</domainCapabilities>
-</pre>
-
- <dl>
- <dt><code>driverType</code></dt>
- <dd>Options for the <code>type</code> attribute of the
- <filesystem><driver> element.</dd>
- </dl>
-
-
- <h3><a id="elementsFeatures">Features</a></h3>
-
- <p>One more set of XML elements describe the supported features and
- their capabilities. All features occur as children of the main
- <code>features</code> element.</p>
-
-<pre>
-<domainCapabilities>
- ...
- <features>
- <gic supported='yes'>
- <enum name='version'>
- <value>2</value>
- <value>3</value>
- </enum>
- </gic>
- <vmcoreinfo supported='yes'/>
- <genid supported='yes'/>
- <backingStoreInput supported='yes'/>
- <backup supported='yes'/>
- <sev>
- <cbitpos>47</cbitpos>
- <reduced-phys-bits>1</reduced-phys-bits>
- </sev>
- </features>
-</domainCapabilities>
-</pre>
-
- <p>Reported capabilities are expressed as an enumerated list of
- possible values for each of the elements or attributes. For example, the
- <code>gic</code> element has an attribute
<code>version</code> which can
- support the values <code>2</code> or
<code>3</code>.</p>
-
- <p>For information about the purpose of each feature, see the
- <a href="formatdomain.html#elementsFeatures">relevant
section</a> in
- the domain XML documentation.
- </p>
-
- <h4><a id="elementsGIC">GIC capabilities</a></h4>
-
- <p>GIC capabilities are exposed under the <code>gic</code>
element.</p>
-
- <dl>
- <dt><code>version</code></dt>
- <dd>Options for the <code>version</code> attribute of the
- <code>gic</code> element.</dd>
- </dl>
-
- <h4><a id="elementsvmcoreinfo">vmcoreinfo</a></h4>
-
- <p>Reports whether the vmcoreinfo feature can be enabled.</p>
-
- <h4><a id="elementsgenid">genid</a></h4>
-
- <p>Reports whether the genid feature can be used by the domain.</p>
-
- <h4><a
id="featureBackingStoreInput">backingStoreInput</a></h4>
-
- <p>Reports whether the hypervisor will obey the <backingStore>
- elements configured for a <disk> when booting the guest, hotplugging
- the disk to a running guest, or similar.
- <span class="since">(Since 5.10)</span>
- </p>
-
- <h4><a id="featureBackup">backup</a></h4>
-
- <p>Reports whether the hypervisor supports the backup, checkpoint, and
- related features. (<code>virDomainBackupBegin</code>,
- <code>virDomainCheckpointCreateXML</code> etc). The presence of the
- <code>backup</code> element even if
<code>supported='no'</code> implies that
- the <code>VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA</code> flag for
- <code>virDomainUndefine</code> is supported.
- </p>
-
- <h4><a id="elementsS390PV">s390-pv
capability</a></h4>
-
- <p>Reports whether the hypervisor supports the Protected Virtualization.
- In order to use Protected Virtualization with libvirt have a look at the
- <a href="formatdomain.html#launchSecurity">launchSecurity element in
the
- domain XML</a>. For more details on the Protected Virtualization feature
- please see <a href="kbase/s390_protected_virt.html">Protected
- Virtualization on s390</a>.
- </p>
-
- <h4><a id="elementsSEV">SEV capabilities</a></h4>
-
- <p>AMD Secure Encrypted Virtualization (SEV) capabilities are exposed under
- the <code>sev</code> element.
- SEV is an extension to the AMD-V architecture which supports running
- virtual machines (VMs) under the control of a hypervisor. When supported,
- guest owner can create a VM whose memory contents will be transparently
- encrypted with a key unique to that VM.</p>
-
- <p>
- For more details on the SEV feature, please follow resources in the
- AMD developer's document store. In order to use SEV with libvirt have
- a look at <a href="formatdomain.html#launchSecurity">SEV in domain
XML</a>
- </p>
-
- <dl>
- <dt><code>cbitpos</code></dt>
- <dd>When memory encryption is enabled, one of the physical address bits
- (aka the C-bit) is utilized to mark if a memory page is protected. The
- C-bit position is Hypervisor dependent.</dd>
- <dt><code>reducedPhysBits</code></dt>
- <dd>When memory encryption is enabled, we lose certain bits in physical
- address space. The number of bits we lose is hypervisor dependent.</dd>
- <dt><code>maxGuests</code></dt>
- <dd>The maximum number of SEV guests that can be launched on the host.
- This value may be configurable in the firmware for some hosts.</dd>
- <dt><code>maxESGuests</code></dt>
- <dd>The maximum number of SEV-ES guests that can be launched on the host.
- This value may be configurable in the firmware for some hosts.</dd>
- </dl>
-
- </body>
-</html>
diff --git a/docs/formatdomaincaps.rst b/docs/formatdomaincaps.rst
new file mode 100644
index 0000000000..c07c07da4b
--- /dev/null
+++ b/docs/formatdomaincaps.rst
@@ -0,0 +1,602 @@
+.. role:: since
+
+==============================
+Domain capabilities XML format
+==============================
+
+.. contents::
+
+Overview
+--------
+
+Sometimes, when a new domain is to be created it may come handy to know the
+capabilities of the hypervisor so the correct combination of devices and drivers
+is used. For example, when management application is considering the mode for a
+host device's passthrough there are several options depending not only on host,
+but on hypervisor in question too. If the hypervisor is qemu then it needs to be
+more recent to support VFIO, while legacy KVM is achievable just fine with older
+qemus.
+
+The main difference between
+`virConnectGetCapabilities
</html/libvirt-libvirt-host.html#virConnectGetCapabilities>`__
+and the emulator capabilities API is, the former one aims more on the host
+capabilities (e.g. NUMA topology, security models in effect, etc.) while the
+latter one specializes on the hypervisor capabilities.
+
+While the `Driver Capabilities <formatcaps.html>`__ provides the host
+capabilities (e.g NUMA topology, security models in effect, etc.), the Domain
+Capabilities provides the hypervisor specific capabilities for Management
+Applications to query and make decisions regarding what to utilize.
+
+The Domain Capabilities can provide information such as the correct combination
+of devices and drivers that are supported. Knowing which host and hypervisor
+specific options are available or supported would allow the management
+application to choose an appropriate mode for a pass-through host device as well
+as which adapter to utilize.
+
+Some XML elements may be entirely omitted from the domaincapabilities XML,
+depending on what the libvirt driver has filled in. Applications should only act
+on what is explicitly reported in the domaincapabilities XML. For example, if
+<disk supported='yes'/> is present, you can safely assume the driver
supports
+<disk> devices. If <disk supported='no'/> is present, you can safely
assume the
+driver does NOT support <disk> devices. If the <disk> block is omitted
entirely,
+the driver is not indicating one way or the other whether it supports <disk>
+devices, and applications should not interpret the missing block to mean any
+thing in particular.
+
+Element and attribute overview
+------------------------------
+
+A new query interface was added to the virConnect API's to retrieve the XML
+listing of the set of domain capabilities ( :since:`Since 1.2.7` ):
+
+::
+
+ virConnectGetDomainCapabilities
+
+The root element that emulator capability XML document starts with has name
+``domainCapabilities``. It contains at least four direct child elements:
+
+::
+
+ <domainCapabilities>
+ <path>/usr/bin/qemu-system-x86_64</path>
+ <domain>kvm</domain>
+ <machine>pc-i440fx-2.1</machine>
+ <arch>x86_64</arch>
+ ...
+ </domainCapabilities>
+
+``path``
+ The full path to the emulator binary.
+``domain``
+ Describes the `virtualization type <formatdomain.html#elements>`__ (or so
+ called domain type).
+``machine``
+ The domain's `machine type <formatdomain.html#elementsOSBIOS>`__. Since not
+ every hypervisor has a sense of machine types this element might be omitted
+ in such drivers.
+``arch``
+ The domain's `architecture <formatdomain.html#elementsOSBIOS>`__.
+
+CPU Allocation
+~~~~~~~~~~~~~~
+
+Before any devices capability occurs, there might be info on domain wide
+capabilities, e.g. virtual CPUs:
+
+::
+
+ <domainCapabilities>
+ ...
+ <vcpu max='255'/>
+ ...
+ </domainCapabilities>
+
+``vcpu``
+ The maximum number of supported virtual CPUs
+
+BIOS bootloader
+~~~~~~~~~~~~~~~
+
+Sometimes users might want to tweak some BIOS knobs or use UEFI. For cases like
+that, `os <formatdomain.html#elementsOSBIOS>`__ element exposes what values can
+be passed to its children.
+
+::
+
+ <domainCapabilities>
+ ...
+ <os supported='yes'>
+ <enum name='firmware'>
+ <value>bios</value>
+ <value>efi</value>
+ </enum>
+ <loader supported='yes'>
+ <value>/usr/share/OVMF/OVMF_CODE.fd</value>
+ <enum name='type'>
+ <value>rom</value>
+ <value>pflash</value>
+ </enum>
+ <enum name='readonly'>
+ <value>yes</value>
+ <value>no</value>
+ </enum>
+ <enum name='secure'>
+ <value>yes</value>
+ <value>no</value>
+ </enum>
+ </loader>
+ </os>
+ ...
+ <domainCapabilities>
+
+The ``firmware`` enum corresponds to the ``firmware`` attribute of the ``os``
+element in the domain XML. The presence of this enum means libvirt is capable of
+the so-called firmware auto-selection feature. And the listed firmware values
+represent the accepted input in the domain XML. Note that the ``firmware`` enum
+reports only those values for which a firmware "descriptor file" exists on the
+host. Firmware descriptor file is a small JSON document that describes details
+about a given BIOS or UEFI binary on the host, e.g. the firmware binary path,
+its architecture, supported machine types, NVRAM template, etc. This ensures
+that the reported values won't cause a failure on guest boot.
+
+For the ``loader`` element, the following can occur:
+
+``value``
+ List of known firmware binary paths. Currently this is used only to advertise
+ the known location of OVMF binaries for QEMU. OVMF binaries will only be
+ listed if they actually exist on host.
+``type``
+ Whether the boot loader is a typical BIOS (``rom``) or a UEFI firmware
+ (``pflash``). Each ``value`` sub-element under the ``type`` enum represents a
+ possible value for the ``type`` attribute for the <loader/> element in the
+ domain XML. E.g. the presence of ``pfalsh`` under the ``type`` enum means
+ that a domain XML can use UEFI firmware via: <loader/> type="pflash"
+ ...>/path/to/the/firmware/binary/</loader>.
+``readonly``
+ Options for the ``readonly`` attribute of the <loader/> element in the domain
+ XML.
+``secure``
+ Options for the ``secure`` attribute of the <loader/> element in the domain
+ XML. Note that the value ``yes`` is listed only if libvirt detects a firmware
+ descriptor file that has path to an OVMF binary that supports Secure boot,
+ and lists its architecture and supported machine type.
+
+CPU configuration
+~~~~~~~~~~~~~~~~~
+
+The ``cpu`` element exposes options usable for configuring `guest
+CPUs <formatdomain.html#elementsCPU>`__.
+
+::
+
+ <domainCapabilities>
+ ...
+ <cpu>
+ <mode name='host-passthrough' supported='yes'>
+ <enum name='hostPassthroughMigratable'>
+ <value>on</value>
+ <value>off</value>
+ </enum>
+ </mode>
+ <mode name='maximum' supported='yes'>
+ <enum name='maximumMigratable'>
+ <value>on</value>
+ <value>off</value>
+ </enum>
+ </mode>
+ <mode name='host-model' supported='yes'>
+ <model fallback='allow'>Broadwell</model>
+ <vendor>Intel</vendor>
+ <feature policy='disable' name='aes'/>
+ <feature policy='require' name='vmx'/>
+ </mode>
+ <mode name='custom' supported='yes'>
+ <model usable='no'
deprecated='no'>Broadwell</model>
+ <model usable='yes'
deprecated='no'>Broadwell-noTSX</model>
+ <model usable='no' deprecated='yes'>Haswell</model>
+ ...
+ </mode>
+ </cpu>
+ ...
+ <domainCapabilities>
+
+Each CPU mode understood by libvirt is described with a ``mode`` element which
+tells whether the particular mode is supported and provides (when applicable)
+more details about it:
+
+``host-passthrough``
+ The ``hostPassthroughMigratable`` enum shows possible values of the
+ ``migratable`` attribute for the <cpu> element with
+ ``mode='host-passthrough'`` in the domain XML.
+``host-model``
+ If ``host-model`` is supported by the hypervisor, the ``mode`` describes the
+ guest CPU which will be used when starting a domain with ``host-model`` CPU.
+ The hypervisor specifics (such as unsupported CPU models or features, machine
+ type, etc.) may be accounted for in this guest CPU specification and thus the
+ CPU can be different from the one shown in host capabilities XML. This is
+ indicated by the ``fallback`` attribute of the ``model`` sub element:
+ ``allow`` means not all specifics were accounted for and thus the CPU a guest
+ will see may be different; ``forbid`` indicates that the CPU a guest will see
+ should match this CPU definition.
+``custom``
+ The ``mode`` element contains a list of supported CPU models, each described
+ by a dedicated ``model`` element. The ``usable`` attribute specifies whether
+ the model can be used directly on the host. When usable='no' the
+ corresponding model cannot be used without disabling some features that the
+ CPU of such model is expected to have. A special value ``unknown`` indicates
+ libvirt does not have enough information to provide the usability data. The
+ ``deprecated`` attribute reflects the hypervisor's policy on usage of this
+ model :since:`(since 7.1.0)` .
+
+I/O Threads
+~~~~~~~~~~~
+
+The ``iothread`` elements indicates whether or not `I/O
+threads <formatdomain.html#elementsIOThreadsAllocation>`__ are supported.
+
+::
+
+ <domainCapabilities>
+ ...
+ <iothread supported='yes'/>
+ ...
+ <domainCapabilities>
+
+Memory Backing
+~~~~~~~~~~~~~~
+
+The ``memory backing`` element indicates whether or not `memory
+backing <formatdomain.html#memory-backing>`__ is supported.
+
+::
+
+ <domainCapabilities>
+ ...
+ <memoryBacking supported='yes'>
+ <enum name='sourceType'>
+ <value>anonymous</value>
+ <value>file</value>
+ <value>memfd</value>
+ </enum>
+ </memoryBacking>
+ ...
+ <domainCapabilities>
+
+``sourceType``
+ Options for the ``type`` attribute of the <memoryBacking><source>
element.
+
+Devices
+~~~~~~~
+
+Another set of XML elements describe the supported devices and their
+capabilities. All devices occur as children of the main ``devices`` element.
+
+::
+
+ <domainCapabilities>
+ ...
+ <devices>
+ <disk supported='yes'>
+ <enum name='diskDevice'>
+ <value>disk</value>
+ <value>cdrom</value>
+ <value>floppy</value>
+ <value>lun</value>
+ </enum>
+ ...
+ </disk>
+ <hostdev supported='no'/>
+ </devices>
+ </domainCapabilities>
+
+Reported capabilities are expressed as an enumerated list of available options
+for each of the element or attribute. For example, the <disk/> element has an
+attribute ``device`` which can support the values ``disk``, ``cdrom``,
+``floppy``, or ``lun``.
+
+Hard drives, floppy disks, CDROMs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Disk capabilities are exposed under the ``disk`` element. For instance:
+
+::
+
+ <domainCapabilities>
+ ...
+ <devices>
+ <disk supported='yes'>
+ <enum name='diskDevice'>
+ <value>disk</value>
+ <value>cdrom</value>
+ <value>floppy</value>
+ <value>lun</value>
+ </enum>
+ <enum name='bus'>
+ <value>ide</value>
+ <value>fdc</value>
+ <value>scsi</value>
+ <value>virtio</value>
+ <value>xen</value>
+ <value>usb</value>
+ <value>sata</value>
+ <value>sd</value>
+ </enum>
+ </disk>
+ ...
+ </devices>
+ </domainCapabilities>
+
+``diskDevice``
+ Options for the ``device`` attribute of the <disk/> element.
+``bus``
+ Options for the ``bus`` attribute of the <target/> element for a <disk/>.
+
+Graphical framebuffers
+^^^^^^^^^^^^^^^^^^^^^^
+
+Graphics device capabilities are exposed under the ``graphics`` element. For
+instance:
+
+::
+
+ <domainCapabilities>
+ ...
+ <devices>
+ <graphics supported='yes'>
+ <enum name='type'>
+ <value>sdl</value>
+ <value>vnc</value>
+ <value>spice</value>
+ </enum>
+ </graphics>
+ ...
+ </devices>
+ </domainCapabilities>
+
+``type``
+ Options for the ``type`` attribute of the <graphics/> element.
+
+Video device
+^^^^^^^^^^^^
+
+Video device capabilities are exposed under the ``video`` element. For instance:
+
+::
+
+ <domainCapabilities>
+ ...
+ <devices>
+ <video supported='yes'>
+ <enum name='modelType'>
+ <value>vga</value>
+ <value>cirrus</value>
+ <value>vmvga</value>
+ <value>qxl</value>
+ <value>virtio</value>
+ </enum>
+ </video>
+ ...
+ </devices>
+ </domainCapabilities>
+
+``modelType``
+ Options for the ``type`` attribute of the <video><model> element.
+
+Host device assignment
+^^^^^^^^^^^^^^^^^^^^^^
+
+Some host devices can be passed through to a guest (e.g. USB, PCI and SCSI).
+Well, only if the following is enabled:
+
+::
+
+ <domainCapabilities>
+ ...
+ <devices>
+ <hostdev supported='yes'>
+ <enum name='mode'>
+ <value>subsystem</value>
+ <value>capabilities</value>
+ </enum>
+ <enum name='startupPolicy'>
+ <value>default</value>
+ <value>mandatory</value>
+ <value>requisite</value>
+ <value>optional</value>
+ </enum>
+ <enum name='subsysType'>
+ <value>usb</value>
+ <value>pci</value>
+ <value>scsi</value>
+ </enum>
+ <enum name='capsType'>
+ <value>storage</value>
+ <value>misc</value>
+ <value>net</value>
+ </enum>
+ <enum name='pciBackend'>
+ <value>default</value>
+ <value>kvm</value>
+ <value>vfio</value>
+ <value>xen</value>
+ </enum>
+ </hostdev>
+ </devices>
+ </domainCapabilities>
+
+``mode``
+ Options for the ``mode`` attribute of the <hostdev/> element.
+``startupPolicy``
+ Options for the ``startupPolicy`` attribute of the <hostdev/> element.
+``subsysType``
+ Options for the ``type`` attribute of the <hostdev/> element in case of
+ ``mode="subsystem"``.
+``capsType``
+ Options for the ``type`` attribute of the <hostdev/> element in case of
+ ``mode="capabilities"``.
+``pciBackend``
+ Options for the ``name`` attribute of the <driver/> element.
+
+RNG device
+^^^^^^^^^^
+
+RNG device capabilities are exposed under the ``rng`` element. For instance:
+
+::
+
+ <domainCapabilities>
+ ...
+ <devices>
+ <rng supported='yes'>
+ <enum name='model'>
+ <value>virtio</value>
+ <value>virtio-transitional</value>
+ <value>virtio-non-transitional</value>
+ </enum>
+ <enum name='backendModel'>
+ <value>random</value>
+ <value>egd</value>
+ <value>builtin</value>
+ </enum>
+ </rng>
+ ...
+ </devices>
+ </domainCapabilities>
+
+``model``
+ Options for the ``model`` attribute of the <rng> element.
+``backendModel``
+ Options for the ``model`` attribute of the <rng><backend> element.
+
+Filesystem device
+^^^^^^^^^^^^^^^^^
+
+Filesystem device capabilities are exposed under the ``filesystem`` element. For
+instance:
+
+::
+
+ <domainCapabilities>
+ ...
+ <devices>
+ <filesystem supported='yes'>
+ <enum name='driverType'>
+ <value>default</value>
+ <value>path</value>
+ <value>handle</value>
+ <value>virtiofs</value>
+ </enum>
+ </filesystem>
+ ...
+ </devices>
+ </domainCapabilities>
+
+``driverType``
+ Options for the ``type`` attribute of the <filesystem><driver> element.
+
+Features
+~~~~~~~~
+
+One more set of XML elements describe the supported features and their
+capabilities. All features occur as children of the main ``features`` element.
+
+::
+
+ <domainCapabilities>
+ ...
+ <features>
+ <gic supported='yes'>
+ <enum name='version'>
+ <value>2</value>
+ <value>3</value>
+ </enum>
+ </gic>
+ <vmcoreinfo supported='yes'/>
+ <genid supported='yes'/>
+ <backingStoreInput supported='yes'/>
+ <backup supported='yes'/>
+ <sev>
+ <cbitpos>47</cbitpos>
+ <reduced-phys-bits>1</reduced-phys-bits>
+ </sev>
+ </features>
+ </domainCapabilities>
+
+Reported capabilities are expressed as an enumerated list of possible values for
+each of the elements or attributes. For example, the ``gic`` element has an
+attribute ``version`` which can support the values ``2`` or ``3``.
+
+For information about the purpose of each feature, see the `relevant
+section <formatdomain.html#elementsFeatures>`__ in the domain XML documentation.
+
+GIC capabilities
+^^^^^^^^^^^^^^^^
+
+GIC capabilities are exposed under the ``gic`` element.
+
+``version``
+ Options for the ``version`` attribute of the ``gic`` element.
+
+vmcoreinfo
+^^^^^^^^^^
+
+Reports whether the vmcoreinfo feature can be enabled.
+
+genid
+^^^^^
+
+Reports whether the genid feature can be used by the domain.
+
+backingStoreInput
+^^^^^^^^^^^^^^^^^
+
+Reports whether the hypervisor will obey the <backingStore> elements configured
+for a <disk> when booting the guest, hotplugging the disk to a running guest, or
+similar. :since:`(Since 5.10)`
+
+backup
+^^^^^^
+
+Reports whether the hypervisor supports the backup, checkpoint, and related
+features. (``virDomainBackupBegin``, ``virDomainCheckpointCreateXML`` etc). The
+presence of the ``backup`` element even if ``supported='no'`` implies that the
+``VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA`` flag for ``virDomainUndefine`` is
+supported.
+
+s390-pv capability
+^^^^^^^^^^^^^^^^^^
+
+Reports whether the hypervisor supports the Protected Virtualization. In order
+to use Protected Virtualization with libvirt have a look at the `launchSecurity
+element in the domain XML <formatdomain.html#launchSecurity>`__. For more
+details on the Protected Virtualization feature please see `Protected
+Virtualization on s390 <kbase/s390_protected_virt.html>`__.
+
+SEV capabilities
+^^^^^^^^^^^^^^^^
+
+AMD Secure Encrypted Virtualization (SEV) capabilities are exposed under the
+``sev`` element. SEV is an extension to the AMD-V architecture which supports
+running virtual machines (VMs) under the control of a hypervisor. When
+supported, guest owner can create a VM whose memory contents will be
+transparently encrypted with a key unique to that VM.
+
+For more details on the SEV feature, please follow resources in the AMD
+developer's document store. In order to use SEV with libvirt have a look at `SEV
+in domain XML <formatdomain.html#launchSecurity>`__
+
+``cbitpos``
+ When memory encryption is enabled, one of the physical address bits (aka the
+ C-bit) is utilized to mark if a memory page is protected. The C-bit position
+ is Hypervisor dependent.
+``reducedPhysBits``
+ When memory encryption is enabled, we lose certain bits in physical address
+ space. The number of bits we lose is hypervisor dependent.
+``maxGuests``
+ The maximum number of SEV guests that can be launched on the host. This value
+ may be configurable in the firmware for some hosts.
+``maxESGuests``
+ The maximum number of SEV-ES guests that can be launched on the host. This
+ value may be configurable in the firmware for some hosts.
diff --git a/docs/kbase/backing_chains.rst b/docs/kbase/backing_chains.rst
index 89920a61b1..38a9a2337b 100644
--- a/docs/kbase/backing_chains.rst
+++ b/docs/kbase/backing_chains.rst
@@ -97,7 +97,7 @@ specification can be used:
</disk>
This makes libvirt follow the settings as configured in the XML. Note that this
-is supported only when the
https://libvirt.org/formatdomaincaps.html#featureBackingStoreInput
+is supported only when the https://libvirt.org/formatdomaincaps.html#backingstoreinput
capability is present.
An empty ``<backingStore/>`` element signals the end of the chain. Using this
diff --git a/docs/meson.build b/docs/meson.build
index 95c9babcf5..81f348398d 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'csharp',
'dbus',
'docs',
- 'formatdomaincaps',
'formatnetwork',
'formatnetworkport',
'formatnode',
@@ -85,6 +84,7 @@ docs_rst_files = [
'formatcaps',
'formatcheckpoint',
'formatdomain',
+ 'formatdomaincaps',
'formatsecret',
'formatsnapshot',
'formatstorage',
--
2.35.1
8:34 a.m.
New subject: [PATCH 18/29] docs: Convert 'formatdomaincaps' to rST
On Mon, Mar 28, 2022 at 02:10:33PM +0200, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
...
+Element and attribute overview
+------------------------------
+
+A new query interface was added to the virConnect API's to retrieve the XML
+listing of the set of domain capabilities ( :since:`Since 1.2.7` ):
+
+::
+
+ virConnectGetDomainCapabilities
Previously, ^this was both verbatim and a href which RST still cannot do IIRC,
so how about we do
`virConnectGetDomainCapabilities
</html/libvirt-libvirt.host.html#virConnectGetDomainCapabilities>`__
instead of verbatim?
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 a.m.
New subject: [PATCH 19/29] docs: Convert 'formatnetworkport' to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatnetworkport.html.in | 223 ---------------------------------
docs/formatnetworkport.rst | 175 ++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 176 insertions(+), 224 deletions(-)
delete mode 100644 docs/formatnetworkport.html.in
create mode 100644 docs/formatnetworkport.rst
diff --git a/docs/formatnetworkport.html.in b/docs/formatnetworkport.html.in
deleted file mode 100644
index 2d41552618..0000000000
--- a/docs/formatnetworkport.html.in
+++ /dev/null
@@ -1,223 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Network XML format</h1>
-
- <ul id="toc">
- </ul>
-
- <p>
- This page provides an introduction to the network port XML format.
- This stores information about the connection between a virtual
- interface of a virtual domain, and the virtual network it is
- attached to.
- </p>
-
- <h2><a id="elements">Element and attribute
overview</a></h2>
-
- <p>
- The root element required for all virtual network ports is
- named <code>networkport</code> and has no configurable attributes
- The network port XML format is available <span class="since">since
- 5.5.0</span>
- </p>
-
- <h3><a id="elementsMetadata">General
metadata</a></h3>
-
- <p>
- The first elements provide basic metadata about the virtual
- network port.
- </p>
-
- <pre>
-<networkport>
- <uuid>7ae63b5f-fe96-4af0-a7c3-da04ba1b3f54</uuid>
- <owner>
- <uuid>06578fc1-c686-46fa-bc2c-220893b466a6</uuid>
- <name>myguest</name>
- </owner>
- <group>webfront</group>
- <mac address='52:54:0:7b:35:93'/>
- ...</pre>
-
- <dl>
- <dt><code>uuid</code></dt>
- <dd>The content of the <code>uuid</code> element provides
- a globally unique identifier for the virtual network port.
- The format must be RFC 4122 compliant, eg
<code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
- If omitted when defining/creating a new network port, a random
- UUID is generated.</dd>
- <dd>The <code>owner</code> node records the domain object that
- is the owner of the network port. It contains two child nodes:
- <dl>
- <dt><code>uuid</code></dt>
- <dd>The content of the <code>uuid</code> element provides
- a globally unique identifier for the virtual domain.</dd>
- <dt><code>name</code></dt>
- <dd>The unique name of the virtual domain</dd>
- </dl>
- </dd>
- <dt><code>group</code></dt>
- <dd>The port group in the virtual network to which the
- port belongs. Can be omitted if no port groups are
- defined on the network.</dd>
- <dt><code>mac</code></dt>
- <dd>The <code>address</code> attribute provides the MAC
- address of the virtual port that will be see by the
- guest. The MAC address must not start with 0xFE as this
- byte is reserved for use on the host side of the port.
- </dd>
- </dl>
-
- <h3><a id="elementsCommon">Common
elements</a></h3>
-
- <p>
- The following elements are common to one or more of the plug
- types listed later
- </p>
-
- <pre>
- ...
- <bandwidth>
- <inbound average='1000' peak='5000' floor='200'
burst='1024'/>
- <outbound average='128' peak='256'
burst='256'/>
- </bandwidth>
- <rxfilters trustGuest='yes'/>
- <port isolated='yes'/>
- <virtualport type='802.1Qbg'>
- <parameters managerid='11' typeid='1193047'
typeidversion='2'/>
- </virtualport>
- ...</pre>
-
- <dl>
- <dt><code>bandwidth</code></dt>
- <dd>This part of the network port XML provides setting quality of service.
- Incoming and outgoing traffic can be shaped independently.
- The <code>bandwidth</code> element and its child elements are
described
- in the <a href="formatnetwork.html#elementQoS">QoS</a>
section of
- the Network XML. In addition the <code>classID</code> attribute may
- exist to provide the ID of the traffic shaping class that is active.
- </dd>
- <dt><code>rxfilters</code></dt>
- <dd>The <code>rxfilters</code> element property
- <code>trustGuest</code> provides the
- capability for the host to detect and trust reports from the
- guest regarding changes to the interface mac address and receive
- filters by setting the attribute to <code>yes</code>. The default
- setting for the attribute is <code>no</code> for security
- reasons and support depends on the guest network device model as
- well as the type of connection on the host - currently it is
- only supported for the virtio device model and for macvtap
- connections on the host.
- </dd>
- <dt><code>port</code></dt>
- <dd> <span class="since">Since 6.1.0.</span>
- The <code>port</code> element property
- <code>isolated</code>, when set to <code>yes</code>
(default
- setting is <code>no</code>) is used to isolate this port's
- network traffic from other ports on the same network that also
- have <code><port isolated='yes'/></code>. This
setting
- is only supported for emulated network devices connected to a
- Linux host bridge via a standard tap device.
- </dd>
- <dt><code>virtualport</code></dt>
- <dd>The <code>virtualport</code> element describes metadata that
- needs to be provided to the underlying network subsystem. It
- is described in the domain XML
- <a href="formatdomain.html#elementsNICS">interface
documentation</a>.
- </dd>
- </dl>
-
-
- <h3><a id="elementsPlug">Plugs</a></h3>
-
- <p>
- The <code>plug</code> element has varying content depending
- on the value of the <code>type</code> attribute.
- </p>
-
- <h4><a id="elementsPlugNetwork">Network</a></h4>
-
- <p>
- The <code>network</code> plug type refers to a managed virtual
- network plug that is based on a traditional software bridge
- device privately managed by libvirt.
- </p>
-
- <pre>
- ...
- <plug type='network' bridge='virbr0'/>
- ...</pre>
-
- <p>
- The <code>bridge</code> attribute provides the name of the
- privately managed bridge device associated with the virtual
- network.
- </p>
-
- <h4><a id="elementsPlugNetwork">Bridge</a></h4>
-
- <p>
- The <code>bridge</code> plug type refers to an externally
- managed traditional software bridge.
- </p>
-
- <pre>
- ...
- <plug type='bridge' bridge='br2'/>
- ...</pre>
-
- <p>
- The <code>bridge</code> attribute provides the name of the
- externally managed bridge device associated with the virtual
- network.
- </p>
-
- <h4><a id="elementsPlugNetwork">Direct</a></h4>
-
- <p>
- The <code>direct</code> plug type refers to a connection
- directly to a physical network interface.
- </p>
-
- <pre>
- ...
- <plug type='direct' dev='ens3' mode='vepa'/>
- ...</pre>
-
- <p>
- The <code>dev</code> attribute provides the name of the
- physical network interface to which the port will be
- connected. The <code>mode</code> attribute describes
- how the connection will be setup and takes the same
- values described in the
- <a href="formatdomain.html#elementsNICSDirect">domain
XML</a>.
- </p>
-
- <h4><a id="elementsPlugNetwork">Host PCI</a></h4>
-
- <p>
- The <code>hostdev-pci</code> plug type refers to the
- passthrough of a physical PCI device rather than emulation.
- </p>
-
- <pre>
- ...
- <plug type='hostdev-pci' managed='yes'>
- <driver name='vfio'/>
- <address domain='0x0001' bus='0x02' slot='0x03'
function='0x4'/>
- </plug>
- ...</pre>
-
- <p>
- The <code>managed</code> attribute indicates who is responsible for
- managing the PCI device in the host. When set to the value
<code>yes</code>
- libvirt is responsible for automatically detaching the device from host
- drivers and resetting it if needed. If the value is <code>no</code>,
- some other party must ensure the device is not attached to any
- host drivers.
- </p>
-
- </body>
-</html>
diff --git a/docs/formatnetworkport.rst b/docs/formatnetworkport.rst
new file mode 100644
index 0000000000..a85888907d
--- /dev/null
+++ b/docs/formatnetworkport.rst
@@ -0,0 +1,175 @@
+.. role:: since
+
+==================
+Network XML format
+==================
+
+.. contents::
+
+This page provides an introduction to the network port XML format. This stores
+information about the connection between a virtual interface of a virtual
+domain, and the virtual network it is attached to.
+
+Element and attribute overview
+------------------------------
+
+The root element required for all virtual network ports is named ``networkport``
+and has no configurable attributes The network port XML format is available
+:since:`since 5.5.0`
+
+General metadata
+~~~~~~~~~~~~~~~~
+
+The first elements provide basic metadata about the virtual network port.
+
+::
+
+ <networkport>
+ <uuid>7ae63b5f-fe96-4af0-a7c3-da04ba1b3f54</uuid>
+ <owner>
+ <uuid>06578fc1-c686-46fa-bc2c-220893b466a6</uuid>
+ <name>myguest</name>
+ </owner>
+ <group>webfront</group>
+ <mac address='52:54:0:7b:35:93'/>
+ ...
+
+``uuid``
+ The content of the ``uuid`` element provides a globally unique identifier for
+ the virtual network port. The format must be RFC 4122 compliant, eg
+ ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/creating a
+ new network port, a random UUID is generated.
+ The ``owner`` node records the domain object that is the owner of the network
+ port. It contains two child nodes:
+
+ ``uuid``
+ The content of the ``uuid`` element provides a globally unique identifier
+ for the virtual domain.
+ ``name``
+ The unique name of the virtual domain
+``group``
+ The port group in the virtual network to which the port belongs. Can be
+ omitted if no port groups are defined on the network.
+``mac``
+ The ``address`` attribute provides the MAC address of the virtual port that
+ will be see by the guest. The MAC address must not start with 0xFE as this
+ byte is reserved for use on the host side of the port.
+
+Common elements
+~~~~~~~~~~~~~~~
+
+The following elements are common to one or more of the plug types listed later
+
+::
+
+ ...
+ <bandwidth>
+ <inbound average='1000' peak='5000' floor='200'
burst='1024'/>
+ <outbound average='128' peak='256' burst='256'/>
+ </bandwidth>
+ <rxfilters trustGuest='yes'/>
+ <port isolated='yes'/>
+ <virtualport type='802.1Qbg'>
+ <parameters managerid='11' typeid='1193047'
typeidversion='2'/>
+ </virtualport>
+ ...
+
+``bandwidth``
+ This part of the network port XML provides setting quality of service.
+ Incoming and outgoing traffic can be shaped independently. The ``bandwidth``
+ element and its child elements are described in the
+ `QoS <formatnetwork.html#elementQoS>`__ section of the Network XML. In
+ addition the ``classID`` attribute may exist to provide the ID of the traffic
+ shaping class that is active.
+``rxfilters``
+ The ``rxfilters`` element property ``trustGuest`` provides the capability for
+ the host to detect and trust reports from the guest regarding changes to the
+ interface mac address and receive filters by setting the attribute to
+ ``yes``. The default setting for the attribute is ``no`` for security reasons
+ and support depends on the guest network device model as well as the type of
+ connection on the host - currently it is only supported for the virtio device
+ model and for macvtap connections on the host.
+``port``
+ :since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to
+ ``yes`` (default setting is ``no``) is used to isolate this port's network
+ traffic from other ports on the same network that also have
+ ``<port isolated='yes'/>``. This setting is only supported for emulated
+ network devices connected to a Linux host bridge via a standard tap device.
+``virtualport``
+ The ``virtualport`` element describes metadata that needs to be provided to
+ the underlying network subsystem. It is described in the domain XML
+ `interface documentation <formatdomain.html#elementsNICS>`__.
+
+Plugs
+~~~~~
+
+The ``plug`` element has varying content depending on the value of the ``type``
+attribute.
+
+Network
+^^^^^^^
+
+The ``network`` plug type refers to a managed virtual network plug that is based
+on a traditional software bridge device privately managed by libvirt.
+
+::
+
+ ...
+ <plug type='network' bridge='virbr0'/>
+ ...
+
+The ``bridge`` attribute provides the name of the privately managed bridge
+device associated with the virtual network.
+
+Bridge
+^^^^^^
+
+The ``bridge`` plug type refers to an externally managed traditional software
+bridge.
+
+::
+
+ ...
+ <plug type='bridge' bridge='br2'/>
+ ...
+
+The ``bridge`` attribute provides the name of the externally managed bridge
+device associated with the virtual network.
+
+Direct
+^^^^^^
+
+The ``direct`` plug type refers to a connection directly to a physical network
+interface.
+
+::
+
+ ...
+ <plug type='direct' dev='ens3' mode='vepa'/>
+ ...
+
+The ``dev`` attribute provides the name of the physical network interface to
+which the port will be connected. The ``mode`` attribute describes how the
+connection will be setup and takes the same values described in the `domain
+XML <formatdomain.html#elementsNICSDirect>`__.
+
+Host PCI
+^^^^^^^^
+
+The ``hostdev-pci`` plug type refers to the passthrough of a physical PCI device
+rather than emulation.
+
+::
+
+ ...
+ <plug type='hostdev-pci' managed='yes'>
+ <driver name='vfio'/>
+ <address domain='0x0001' bus='0x02' slot='0x03'
function='0x4'/>
+ </plug>
+ ...
+
+The ``managed`` attribute indicates who is responsible for managing the PCI
+device in the host. When set to the value ``yes`` libvirt is responsible for
+automatically detaching the device from host drivers and resetting it if needed.
+If the value is ``no``, some other party must ensure the device is not attached
+to any host drivers.
diff --git a/docs/meson.build b/docs/meson.build
index 81f348398d..bb1359aacd 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -23,7 +23,6 @@ docs_html_in_files = [
'dbus',
'docs',
'formatnetwork',
- 'formatnetworkport',
'formatnode',
'formatnwfilter',
'formatstoragecaps',
@@ -85,6 +84,7 @@ docs_rst_files = [
'formatcheckpoint',
'formatdomain',
'formatdomaincaps',
+ 'formatnetworkport',
'formatsecret',
'formatsnapshot',
'formatstorage',
--
2.35.1
7:10 a.m.
New subject: [PATCH 20/29] docs: Fix heading of 'formatnetworkport' page
The top level heading didn't contain the word 'port'.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatnetworkport.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/formatnetworkport.rst b/docs/formatnetworkport.rst
index a85888907d..86a1bdb60b 100644
--- a/docs/formatnetworkport.rst
+++ b/docs/formatnetworkport.rst
@@ -1,8 +1,8 @@
.. role:: since
-==================
-Network XML format
-==================
+=======================
+Network port XML format
+=======================
.. contents::
--
2.35.1
8:36 a.m.
New subject: [PATCH 20/29] docs: Fix heading of 'formatnetworkport' page
On Mon, Mar 28, 2022 at 02:10:35PM +0200, Peter Krempa wrote:
The top level heading didn't contain the word 'port'.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 a.m.
New subject: [PATCH 21/29] docs: Convert 'formatstoragecaps' page to rST
Note that if we want to preserve the link from the code block hilighting
'virConnectGetStoragePoolCapabilities' we'd need to re-stylize it as rST
doesn't support nesting of links into preformatted code blocks.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatstoragecaps.html.in | 95 ----------------------------------
docs/formatstoragecaps.rst | 81 +++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 82 insertions(+), 96 deletions(-)
delete mode 100644 docs/formatstoragecaps.html.in
create mode 100644 docs/formatstoragecaps.rst
diff --git a/docs/formatstoragecaps.html.in b/docs/formatstoragecaps.html.in
deleted file mode 100644
index a9ecc371fa..0000000000
--- a/docs/formatstoragecaps.html.in
+++ /dev/null
@@ -1,95 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Storage Pool Capabilities XML format</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="Overview">Overview</a></h2>
-
- <p>The Storage Pool Capabilities XML will provide the information
- to determine what types of Storage Pools exist, whether the pool is
- supported, and if relevant the source format types, the required
- source elements, and the target volume format types. </p>
-
- <h2><a id="elements">Element and attribute
overview</a></h2>
-
- <p>A query interface was added to the virConnect API's to retrieve the
- XML listing of the set of Storage Pool Capabilities
- (<span class="since">Since 5.2.0</span>):</p>
-
-<pre>
-<a
href="/html/libvirt-libvirt-storage.html#virConnectGetStoragePoolCapabilities">virConnectGetStoragePoolCapabilities</a>
-</pre>
-
- <p>The root element that emulator capability XML document starts with is
- named <code>storagepoolCapabilities</code>. There will be any number of
- <code>pool</code> child elements with two attributes
<code>type</code>
- and <code>supported</code>. Each <code>pool</code> element
may have
- a <code>poolOptions</code> or <code>volOptions</code>
subelements to
- describe the available features. Sample XML output is:</p>
-
-<pre>
-<storagepoolCapabilities>
- <pool type='dir' supported='yes'>
- <volOptions>
- <defaultFormat type='raw'</>
- <enum name='targetFormatType'>
- <value>none</value>
- <value>raw</value>
- ...
- </enum>
- </volOptions>
- </pool>
- <pool type='fs' supported='yes'>
- <poolOptions>
- <defaultFormat type='auto'</>
- <enum name='sourceFormatType'>
- <value>auto</value>
- <value>ext2</value>
- ...
- </enum>
- </poolOptions>
- <volOptions>
- <defaultFormat type='raw'</>
- <enum name='targetFormatType'>
- <value>none</value>
- <value>raw</value>
- ...
- </enum>
- </volOptions>
- </pool>
- ...
-</storagepoolCapabilities>
-</pre>
-
- <p>The following section describes subelements of the
- <code>poolOptions</code> and <code>volOptions</code>
subelements </p>:
-
- <dl>
- <dt><code>defaultFormat</code></dt>
- <dd>For the <code>poolOptions</code>, the
<code>type</code> attribute
- describes the default format name used for the pool source. For the
- <code>volOptions</code>, the <code>type</code> attribute
describes
- the default volume name used for each volume.
- </dd>
- <dl>
- <dt><code>enum</code></dt>
- <dd>Each enum uses a name from the list below with any number of
- <code>value</code> value subelements describing the valid values.
- <dl>
- <dt><code>sourceFormatType</code></dt>
- <dd>Lists all the possible <code>poolOptions</code> source
- pool format types.
- </dd>
- <dt><code>targetFormatType</code></dt>
- <dd>Lists all the possible <code>volOptions</code> target
volume
- format types.
- </dd>
- </dl>
- </dd>
- </dl>
- </dl>
- </body>
-</html>
diff --git a/docs/formatstoragecaps.rst b/docs/formatstoragecaps.rst
new file mode 100644
index 0000000000..32cd392931
--- /dev/null
+++ b/docs/formatstoragecaps.rst
@@ -0,0 +1,81 @@
+.. role:: since
+
+====================================
+Storage Pool Capabilities XML format
+====================================
+
+.. contents::
+
+Overview
+--------
+
+The Storage Pool Capabilities XML will provide the information to determine what
+types of Storage Pools exist, whether the pool is supported, and if relevant the
+source format types, the required source elements, and the target volume format
+types.
+
+Element and attribute overview
+------------------------------
+
+A query interface was added to the virConnect API's to retrieve the XML listing
+of the set of Storage Pool Capabilities ( :since:`Since 5.2.0` ):
+
+::
+
+ virConnectGetStoragePoolCapabilities
+
+The root element that emulator capability XML document starts with is named
+``storagepoolCapabilities``. There will be any number of ``pool`` child elements
+with two attributes ``type`` and ``supported``. Each ``pool`` element may have a
+``poolOptions`` or ``volOptions`` subelements to describe the available
+features. Sample XML output is:
+
+::
+
+ <storagepoolCapabilities>
+ <pool type='dir' supported='yes'>
+ <volOptions>
+ <defaultFormat type='raw'</>
+ <enum name='targetFormatType'>
+ <value>none</value>
+ <value>raw</value>
+ ...
+ </enum>
+ </volOptions>
+ </pool>
+ <pool type='fs' supported='yes'>
+ <poolOptions>
+ <defaultFormat type='auto'</>
+ <enum name='sourceFormatType'>
+ <value>auto</value>
+ <value>ext2</value>
+ ...
+ </enum>
+ </poolOptions>
+ <volOptions>
+ <defaultFormat type='raw'</>
+ <enum name='targetFormatType'>
+ <value>none</value>
+ <value>raw</value>
+ ...
+ </enum>
+ </volOptions>
+ </pool>
+ ...
+ </storagepoolCapabilities>
+
+The following section describes subelements of the ``poolOptions`` and
+``volOptions`` subelements
+
+``defaultFormat``
+ For the ``poolOptions``, the ``type`` attribute describes the default format
+ name used for the pool source. For the ``volOptions``, the ``type`` attribute
+ describes the default volume name used for each volume.
+``enum``
+ Each enum uses a name from the list below with any number of ``value`` value
+ subelements describing the valid values.
+
+ ``sourceFormatType``
+ Lists all the possible ``poolOptions`` source pool format types.
+ ``targetFormatType``
+ Lists all the possible ``volOptions`` target volume format types.
diff --git a/docs/meson.build b/docs/meson.build
index bb1359aacd..b911292480 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -25,7 +25,6 @@ docs_html_in_files = [
'formatnetwork',
'formatnode',
'formatnwfilter',
- 'formatstoragecaps',
'formatstorageencryption',
'hooks',
'index',
@@ -88,6 +87,7 @@ docs_rst_files = [
'formatsecret',
'formatsnapshot',
'formatstorage',
+ 'formatstoragecaps',
'glib-adoption',
'goals',
'governance',
--
2.35.1
8:38 a.m.
New subject: [PATCH 21/29] docs: Convert 'formatstoragecaps' page to rST
On Mon, Mar 28, 2022 at 02:10:36PM +0200, Peter Krempa wrote:
Note that if we want to preserve the link from the code block
hilighting
'virConnectGetStoragePoolCapabilities' we'd need to re-stylize it as rST
doesn't support nesting of links into preformatted code blocks.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
...
+A query interface was added to the virConnect API's to retrieve
the XML listing
+of the set of Storage Pool Capabilities ( :since:`Since 5.2.0` ):
+
+::
+
+ virConnectGetStoragePoolCapabilities
Here too it should IMO be a ref instead of verbatim.
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 a.m.
New subject: [PATCH 22/29] docs: Convert 'formatstorageencryption' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatstorageencryption.html.in | 181 ---------------------------
docs/formatstorageencryption.rst | 142 +++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 143 insertions(+), 182 deletions(-)
delete mode 100644 docs/formatstorageencryption.html.in
create mode 100644 docs/formatstorageencryption.rst
diff --git a/docs/formatstorageencryption.html.in b/docs/formatstorageencryption.html.in
deleted file mode 100644
index 395a7269b1..0000000000
--- a/docs/formatstorageencryption.html.in
+++ /dev/null
@@ -1,181 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Storage volume encryption XML format</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="StorageEncryption">Storage volume encryption
XML</a></h2>
-
- <p>
- Storage volumes may be encrypted, the XML snippet described below is used
- to represent the details of the encryption. It can be used as a part
- of a domain or storage configuration.
- </p>
- <p>
- The top-level tag of volume encryption specification
- is <code>encryption</code>, with a mandatory
- attribute <code>format</code>. Currently defined values
- of <code>format</code> are <code>default</code>,
<code>qcow</code>,
- <code>luks</code>, and <code>luks2</code>.
- Each value of <code>format</code> implies some expectations about the
- content of the <code>encryption</code> tag. Other format values may
be
- defined in the future.
- </p>
- <p>
- The <code>encryption</code> tag supports an optional
<code>engine</code>
- tag, which allows selecting which component actually handles
- the encryption. Currently defined values of <code>engine</code> are
- <code>qemu</code> and <code>librbd</code>.
- Both <code>qemu</code> and <code>librbd</code> require
using the qemu
- driver.
- The <code>librbd</code> engine requires qemu version >= 6.1.0, both
- ceph cluster and librbd1 >= 16.1.0, and is only applicable for RBD
- network disks.
- If the engine tag is not specified, the <code>qemu</code> engine will
be
- used by default (assuming the qemu driver is used).
- Note that <code>librbd</code> engine is currently only supported by
the
- qemu VM driver, and is not supported by the storage driver. Furthermore,
- the storage driver currently ignores the <code>engine</code> tag.
- </p>
- <p>
- The <code>encryption</code> tag can currently contain a sequence of
- <code>secret</code> tags, each with mandatory attributes
<code>type</code>
- and either <code>uuid</code> or <code>usage</code>
- (<span class="since">since 2.1.0</span>). The only currently
defined
- value of <code>type</code> is <code>volume</code>. The
- <code>uuid</code> is "uuid" of the
<code>secret</code> while
- <code>usage</code> is the "usage" subelement field.
- A secret value can be set in libvirt by the
- <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
- <code>virSecretSetValue</code></a> API. Alternatively, if
supported
- by the particular volume format and driver, automatically generate a
- secret value at the time of volume creation, and store it using the
- specified <code>uuid</code>.
- </p>
- <h3><a id="StorageEncryptionDefault">"default"
format</a></h3>
- <h3><a id="StorageEncryptionQcow">"qcow"
format</a></h3>
- <p>
- <span class="since">Since 4.5.0,</span> encryption formats
- <code>default</code> and <code>qcow</code> may no longer be
used
- to create an encrypted volume. Usage of qcow encrypted volumes
- in QEMU began phasing out in QEMU 2.3 and by QEMU 2.9 creation
- of a qcow encrypted volume via qemu-img required usage of secret
- objects, but that support was not added to libvirt.
- </p>
- <h3><a id="StorageEncryptionLuks">"luks"
format</a></h3>
- <p>
- The <code>luks</code> format is specific to a luks encrypted volume
- and the secret is used in order to either encrypt during volume creation
- or decrypt the volume for usage by the domain. A single
- <code><secret type='passphrase'...></code>
element is expected.
- <span class="since">Since 2.1.0</span>.
- </p>
- <p>
- For volume creation, it is possible to specify the encryption
- algorithm used to encrypt the luks volume. The following two
- optional elements may be provided for that purpose. It is hypervisor
- dependent as to which algorithms are supported. The default algorithm
- used by the storage driver backend when using qemu-img to create
- the volume is 'aes-256-cbc' using 'essiv' for initialization
vector
- generation and 'sha256' hash algorithm for both the cipher and the
- initialization vector generation.
- </p>
-
- <dl>
- <dt><code>cipher</code></dt>
- <dd>This element describes the cipher algorithm to be used to either
- encrypt or decrypt the luks volume. This element has the following
- attributes:
- <dl>
- <dt><code>name</code></dt>
- <dd>The name of the cipher algorithm used for data encryption,
- such as 'aes', 'des', 'cast5', 'serpent',
'twofish', etc.
- Support of the specific algorithm is storage driver
- implementation dependent.</dd>
- <dt><code>size</code></dt>
- <dd>The size of the cipher in bits, such as '256',
'192', '128',
- etc. Support of the specific size for a specific cipher is
- hypervisor dependent.</dd>
- <dt><code>mode</code></dt>
- <dd>An optional cipher algorithm mode such as 'cbc',
'xts',
- 'ecb', etc. Support of the specific cipher mode is
- hypervisor dependent.</dd>
- <dt><code>hash</code></dt>
- <dd>An optional master key hash algorithm such as 'md5',
'sha1',
- 'sha256', etc. Support of the specific hash algorithm is
- hypervisor dependent.</dd>
- </dl>
- </dd>
- <dt><code>ivgen</code></dt>
- <dd>This optional element describes the initialization vector
- generation algorithm used in conjunction with the
- <code>cipher</code>. If the <code>cipher</code> is not
provided,
- then an error will be generated by the parser.
- <dl>
- <dt><code>name</code></dt>
- <dd>The name of the algorithm, such as 'plain',
'plain64',
- 'essiv', etc. Support of the specific algorithm is hypervisor
- dependent.</dd>
- <dt><code>hash</code></dt>
- <dd>An optional hash algorithm such as 'md5', 'sha1',
'sha256',
- etc. Support of the specific ivgen hash algorithm is hypervisor
- dependent.</dd>
- </dl>
- </dd>
- </dl>
-
- <h3><a id="StorageEncryptionLuks2">"luks2"
format</a></h3>
- <p>
- The <code>luks2</code> format is currently supported only by the
- <code>librbd</code> engine, and can only be applied to RBD network
disks
- (RBD images).
- Since the <code>librbd</code> engine is currently not supported by the
- libvirt storage driver, you cannot use it to control such disks. However,
- pre-formatted RBD luks2 disks can be loaded to a qemu VM using the qemu
- VM driver.
- A single
- <code><secret type='passphrase'...></code>
element is expected.
- </p>
-
-
- <h2><a id="example">Examples</a></h2>
-
- <p>
- Assuming a <a href="formatsecret.html#usage-type-volume">
- <code>luks volume type secret</code></a> is already defined,
- a simple example specifying use of the <code>luks</code> format
- for either volume creation without a specific cipher being defined or
- as part of a domain volume definition:
- </p>
- <pre>
-<encryption format='luks'>
- <secret type='passphrase'
uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
-</encryption>
- </pre>
-
- <p>
- Here is an example specifying use of the <code>luks</code> format for
- a specific cipher algorithm for volume creation.
- <span class="since">Since 6.10.0,</span> the
<code>target</code> format
- can also support <code>qcow2</code> type with
<code>luks</code> encryption.
- </p>
- <pre>
-<volume>
- <name>twofish.luks</name>
- <capacity unit='G'>5</capacity>
- <target>
- <path>/var/lib/libvirt/images/demo.luks</path>
- <format type='raw'/>
- <encryption format='luks'>
- <secret type='passphrase'
uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
- <cipher name='twofish' size='256' mode='cbc'
hash='sha256'/>
- <ivgen name='plain64' hash='sha256'/>
- </encryption>
- </target>
-</volume>
- </pre>
-
- </body>
-</html>
diff --git a/docs/formatstorageencryption.rst b/docs/formatstorageencryption.rst
new file mode 100644
index 0000000000..7b5cccaf5e
--- /dev/null
+++ b/docs/formatstorageencryption.rst
@@ -0,0 +1,142 @@
+.. role:: since
+
+====================================
+Storage volume encryption XML format
+====================================
+
+.. contents::
+
+Storage volume encryption XML
+-----------------------------
+
+Storage volumes may be encrypted, the XML snippet described below is used to
+represent the details of the encryption. It can be used as a part of a domain or
+storage configuration.
+
+The top-level tag of volume encryption specification is ``encryption``, with a
+mandatory attribute ``format``. Currently defined values of ``format`` are
+``default``, ``qcow``, ``luks``, and ``luks2``. Each value of ``format`` implies
+some expectations about the content of the ``encryption`` tag. Other format
+values may be defined in the future.
+
+The ``encryption`` tag supports an optional ``engine`` tag, which allows
+selecting which component actually handles the encryption. Currently defined
+values of ``engine`` are ``qemu`` and ``librbd``. Both ``qemu`` and ``librbd``
+require using the qemu driver. The ``librbd`` engine requires qemu version >=
+6.1.0, both ceph cluster and librbd1 >= 16.1.0, and is only applicable for RBD
+network disks. If the engine tag is not specified, the ``qemu`` engine will be
+used by default (assuming the qemu driver is used). Note that ``librbd`` engine
+is currently only supported by the qemu VM driver, and is not supported by the
+storage driver. Furthermore, the storage driver currently ignores the ``engine``
+tag.
+
+The ``encryption`` tag can currently contain a sequence of ``secret`` tags, each
+with mandatory attributes ``type`` and either ``uuid`` or ``usage`` (
+:since:`since 2.1.0` ). The only currently defined value of ``type`` is
+``volume``. The ``uuid`` is "uuid" of the ``secret`` while ``usage`` is the
+"usage" subelement field. A secret value can be set in libvirt by the
+`virSecretSetValue <html/libvirt-libvirt-secret.html#virSecretSetValue>`__ API.
+Alternatively, if supported by the particular volume format and driver,
+automatically generate a secret value at the time of volume creation, and store
+it using the specified ``uuid``.
+
+"default" format
+~~~~~~~~~~~~~~~~
+
+"qcow" format
+~~~~~~~~~~~~~
+
+:since:`Since 4.5.0,` encryption formats ``default`` and ``qcow`` may no longer
+be used to create an encrypted volume. Usage of qcow encrypted volumes in QEMU
+began phasing out in QEMU 2.3 and by QEMU 2.9 creation of a qcow encrypted
+volume via qemu-img required usage of secret objects, but that support was not
+added to libvirt.
+
+"luks" format
+~~~~~~~~~~~~~
+
+The ``luks`` format is specific to a luks encrypted volume and the secret is
+used in order to either encrypt during volume creation or decrypt the volume for
+usage by the domain. A single ``<secret type='passphrase'...>`` element is
+expected. :since:`Since 2.1.0` .
+
+For volume creation, it is possible to specify the encryption algorithm used to
+encrypt the luks volume. The following two optional elements may be provided for
+that purpose. It is hypervisor dependent as to which algorithms are supported.
+The default algorithm used by the storage driver backend when using qemu-img to
+create the volume is 'aes-256-cbc' using 'essiv' for initialization
vector
+generation and 'sha256' hash algorithm for both the cipher and the
+initialization vector generation.
+
+``cipher``
+ This element describes the cipher algorithm to be used to either encrypt or
+ decrypt the luks volume. This element has the following attributes:
+
+ ``name``
+ The name of the cipher algorithm used for data encryption, such as 'aes',
+ 'des', 'cast5', 'serpent', 'twofish', etc. Support
of the specific
+ algorithm is storage driver implementation dependent.
+ ``size``
+ The size of the cipher in bits, such as '256', '192',
'128', etc. Support
+ of the specific size for a specific cipher is hypervisor dependent.
+ ``mode``
+ An optional cipher algorithm mode such as 'cbc', 'xts',
'ecb', etc.
+ Support of the specific cipher mode is hypervisor dependent.
+ ``hash``
+ An optional master key hash algorithm such as 'md5', 'sha1',
'sha256',
+ etc. Support of the specific hash algorithm is hypervisor dependent.
+``ivgen``
+ This optional element describes the initialization vector generation
+ algorithm used in conjunction with the ``cipher``. If the ``cipher`` is not
+ provided, then an error will be generated by the parser.
+
+ ``name``
+ The name of the algorithm, such as 'plain', 'plain64',
'essiv', etc.
+ Support of the specific algorithm is hypervisor dependent.
+ ``hash``
+ An optional hash algorithm such as 'md5', 'sha1', 'sha256',
etc. Support
+ of the specific ivgen hash algorithm is hypervisor dependent.
+
+"luks2" format
+~~~~~~~~~~~~~~
+
+The ``luks2`` format is currently supported only by the ``librbd`` engine, and
+can only be applied to RBD network disks (RBD images). Since the ``librbd``
+engine is currently not supported by the libvirt storage driver, you cannot use
+it to control such disks. However, pre-formatted RBD luks2 disks can be loaded
+to a qemu VM using the qemu VM driver. A single
+``<secret type='passphrase'...>`` element is expected.
+
+Examples
+--------
+
+Assuming a `luks volume type secret <formatsecret.html#VolumeUsageType>`__ is
+already defined, a simple example specifying use of the ``luks`` format for
+either volume creation without a specific cipher being defined or as part of a
+domain volume definition:
+
+::
+
+ <encryption format='luks'>
+ <secret type='passphrase'
uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
+ </encryption>
+
+Here is an example specifying use of the ``luks`` format for a specific cipher
+algorithm for volume creation. :since:`Since 6.10.0,` the ``target`` format can
+also support ``qcow2`` type with ``luks`` encryption.
+
+::
+
+ <volume>
+ <name>twofish.luks</name>
+ <capacity unit='G'>5</capacity>
+ <target>
+ <path>/var/lib/libvirt/images/demo.luks</path>
+ <format type='raw'/>
+ <encryption format='luks'>
+ <secret type='passphrase'
uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
+ <cipher name='twofish' size='256' mode='cbc'
hash='sha256'/>
+ <ivgen name='plain64' hash='sha256'/>
+ </encryption>
+ </target>
+ </volume>
diff --git a/docs/meson.build b/docs/meson.build
index b911292480..22eca7d8bd 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -25,7 +25,6 @@ docs_html_in_files = [
'formatnetwork',
'formatnode',
'formatnwfilter',
- 'formatstorageencryption',
'hooks',
'index',
'internals',
@@ -88,6 +87,7 @@ docs_rst_files = [
'formatsnapshot',
'formatstorage',
'formatstoragecaps',
+ 'formatstorageencryption',
'glib-adoption',
'goals',
'governance',
--
2.35.1
7:10 a.m.
New subject: [PATCH 23/29] docs: formatstorageencryption: Drop empty 'default' paragraph
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatstorageencryption.rst | 3 ---
1 file changed, 3 deletions(-)
diff --git a/docs/formatstorageencryption.rst b/docs/formatstorageencryption.rst
index 7b5cccaf5e..1c7227040e 100644
--- a/docs/formatstorageencryption.rst
+++ b/docs/formatstorageencryption.rst
@@ -40,9 +40,6 @@ Alternatively, if supported by the particular volume format and driver,
automatically generate a secret value at the time of volume creation, and store
it using the specified ``uuid``.
-"default" format
-~~~~~~~~~~~~~~~~
-
"qcow" format
~~~~~~~~~~~~~
--
2.35.1
7:10 a.m.
New subject: [PATCH 24/29] docs: formatstorageencryption: Re-style encryption type headers
Use backticks to force monospace font instead of double quotes.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatstorageencryption.rst | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/docs/formatstorageencryption.rst b/docs/formatstorageencryption.rst
index 1c7227040e..11bea53cb8 100644
--- a/docs/formatstorageencryption.rst
+++ b/docs/formatstorageencryption.rst
@@ -40,8 +40,8 @@ Alternatively, if supported by the particular volume format and driver,
automatically generate a secret value at the time of volume creation, and store
it using the specified ``uuid``.
-"qcow" format
-~~~~~~~~~~~~~
+``qcow`` format
+~~~~~~~~~~~~~~~
:since:`Since 4.5.0,` encryption formats ``default`` and ``qcow`` may no longer
be used to create an encrypted volume. Usage of qcow encrypted volumes in QEMU
@@ -49,8 +49,8 @@ began phasing out in QEMU 2.3 and by QEMU 2.9 creation of a qcow
encrypted
volume via qemu-img required usage of secret objects, but that support was not
added to libvirt.
-"luks" format
-~~~~~~~~~~~~~
+``luks`` format
+~~~~~~~~~~~~~~~
The ``luks`` format is specific to a luks encrypted volume and the secret is
used in order to either encrypt during volume creation or decrypt the volume for
@@ -94,8 +94,8 @@ initialization vector generation.
An optional hash algorithm such as 'md5', 'sha1', 'sha256',
etc. Support
of the specific ivgen hash algorithm is hypervisor dependent.
-"luks2" format
-~~~~~~~~~~~~~~
+``luks2`` format
+~~~~~~~~~~~~~~~~
The ``luks2`` format is currently supported only by the ``librbd`` engine, and
can only be applied to RBD network disks (RBD images). Since the ``librbd``
--
2.35.1
8:45 a.m.
New subject: [PATCH 24/29] docs: formatstorageencryption: Re-style encryption type headers
On Mon, Mar 28, 2022 at 02:10:39PM +0200, Peter Krempa wrote:
Use backticks to force monospace font instead of double quotes.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 a.m.
New subject: [PATCH 25/29] docs: Convert 'hooks' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/hooks.html.in | 406 -----------------------------------
docs/hooks.rst | 518 +++++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 519 insertions(+), 407 deletions(-)
delete mode 100644 docs/hooks.html.in
create mode 100644 docs/hooks.rst
diff --git a/docs/hooks.html.in b/docs/hooks.html.in
deleted file mode 100644
index bbbc414dc4..0000000000
--- a/docs/hooks.html.in
+++ /dev/null
@@ -1,406 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Hooks for specific system management</h1>
-
- <ul id="toc"></ul>
-
- <h2><a id="intro">Custom event scripts</a></h2>
- <p>Beginning with libvirt 0.8.0, specific events on a host system will
- trigger custom scripts.</p>
- <p>These custom <b>hook</b> scripts are executed when any of the
following
- actions occur:</p>
- <ul>
- <li>The libvirt daemon starts, stops, or reloads its
- configuration
- (<span class="since">since
0.8.0</span>)<br/><br/></li>
- <li>A QEMU guest is started or stopped
- (<span class="since">since
0.8.0</span>)<br/><br/></li>
- <li>An LXC guest is started or stopped
- (<span class="since">since
0.8.0</span>)<br/><br/></li>
- <li>A libxl-handled Xen guest is started or stopped
- (<span class="since">since
2.1.0</span>)<br/><br/></li>
- <li>A network is started or stopped or an interface is
- plugged/unplugged to/from the network
- (<span class="since">since
1.2.2</span>)<br/><br/></li>
- </ul>
-
- <h2><a id="location">Script location</a></h2>
- <p>The libvirt hook scripts are located in the directory
- <code>$SYSCONFDIR/libvirt/hooks/</code>.</p>
- <ul>
- <li>In Linux distributions such as Fedora and RHEL, this is
- <code>/etc/libvirt/hooks/</code>. Other Linux distributions may
do
- this differently.</li>
- <li>If your installation of libvirt has instead been compiled from
- source, it is likely to be
- <code>/usr/local/etc/libvirt/hooks/</code>.</li>
- <li><span class="since">Since 6.5.0</span>, you can
also place several
- hook scripts in the directories
-
<code>/etc/libvirt/hooks/<driver>.d/</code>.</li>
- </ul>
- <p>To use hook scripts, you will need to create this
<code>hooks</code>
- directory manually, place the desired hook scripts inside, then make
- them executable.</p>
- <br/>
-
- <h2><a id="names">Script names</a></h2>
- <p>At present, there are five hook scripts that can be called:</p>
- <ul>
- <li><code>/etc/libvirt/hooks/daemon</code><br/><br/>
- Executed when the libvirt daemon is started, stopped, or reloads
- its configuration<br/><br/></li>
- <li><code>/etc/libvirt/hooks/qemu</code><br/><br/>
- Executed when a QEMU guest is started, stopped, or
migrated<br/><br/></li>
- <li><code>/etc/libvirt/hooks/lxc</code><br /><br/>
- Executed when an LXC guest is started or stopped</li>
- <li><code>/etc/libvirt/hooks/libxl</code><br/><br/>
- Executed when a libxl-handled Xen guest is started, stopped, or
- migrated<br/><br/></li>
-
<li><code>/etc/libvirt/hooks/network</code><br/><br/>
- Executed when a network is started or stopped or an
- interface is plugged/unplugged to/from the network</li>
- </ul>
- <p><span class="since">Since 6.5.0</span>, you can also
have
- several scripts with any name in the directories
- <code>/etc/libvirt/hooks/<driver>.d/</code>. They are
- executed in alphabetical order after main script.</p>
- <br/>
-
- <h2><a id="structure">Script structure</a></h2>
- <p>The hook scripts are executed using standard Linux process creation
- functions. Therefore, they must begin with the declaration of the
- command interpreter to use.</p>
- <p>For example:</p>
- <pre>#!/bin/bash</pre>
- <p>or:</p>
- <pre>#!/usr/bin/python</pre>
- <p>Other command interpreters are equally valid, as is any executable
- binary, so you are welcome to use your favourite languages.</p>
- <br/>
-
- <h2><a id="arguments">Script arguments</a></h2>
- <p>The hook scripts are called with specific command line arguments,
- depending upon the script, and the operation being performed.</p>
- <p>The guest hook scripts, qemu and lxc, are also given the
<b>full</b>
- XML description for the domain on their stdin. This includes items
- such the UUID of the domain and its storage information, and is
- intended to provide all the libvirt information the script needs.</p>
- <p>For all cases, stdin of the network hook script is provided with the
- full XML description of the network status in the following form:</p>
-
-<pre><hookData>
- <network>
- <name>$network_name</name>
- <uuid>afca425a-2c3a-420c-b2fb-dd7b4950d722</uuid>
- ...
- </network>
-</hookData></pre>
-
- <p>In the case of an network port being created / deleted, the network
- XML will be followed with the full XML description of the port:</p>
-
-<pre><hookData>
- <network>
- <name>$network_name</name>
- <uuid>afca425a-2c3a-420c-b2fb-dd7b4950d722</uuid>
- ...
- </network>
- <networkport>
- <uuid>5d744f21-ba4a-4d6e-bdb2-30a35ff3207d</uuid>
- ...
- <plug type='direct' dev='ens3' mode='vepa'/>
- </networkport>
-</hookData></pre>
-
- <p>Please note that this approach is different from other cases such as
- <code>daemon</code>, <code>qemu</code> or
<code>lxc</code> hook scripts,
- because two XMLs may be passed here, while in the other cases only a single
- XML is passed.</p>
-
- <p>The command line arguments take this approach:</p>
- <ol>
- <li>The first argument is the name of the <b>object</b> involved
in the
- operation, or '-' if there is none.<br/><br/>
- For example, the name of a guest being
started.<br/><br/></li>
- <li>The second argument is the name of the <b>operation</b>
being
- performed.<br/><br/>
- For example, "start" if a guest is being
started.<br/><br/></li>
- <li>The third argument is a <b>sub-operation</b> indication, or
'-' if there
- is none.<br/><br/></li>
- <li>The last argument is an <b>extra argument</b> string, or
'-' if there is
- none.</li>
- </ol>
-
- <h4><a id="arguments_specifics">Specifics</a></h4>
- <p>This translates to the following specifics for each hook script:</p>
-
- <h5><a
id="daemon">/etc/libvirt/hooks/daemon</a></h5>
- <ul>
- <li>When the libvirt daemon is started, this script is called as:<br/>
- <pre>/etc/libvirt/hooks/daemon - start - start</pre></li>
- <li>When the libvirt daemon is shut down, this script is called
as:<br/>
- <pre>/etc/libvirt/hooks/daemon - shutdown -
shutdown</pre></li>
- <li>When the libvirt daemon receives the SIGHUP signal, it reloads its
- configuration and triggers the hook script as:<br/>
- <pre>/etc/libvirt/hooks/daemon - reload begin
SIGHUP</pre></li>
- </ul>
- <p>Please note that when the libvirt daemon is restarted, the
<i>daemon</i>
- hook script is called once with the "shutdown" operation, and then once
- with the "start" operation. There is no specific operation to indicate
- a "restart" is occurring.</p>
-
- <h5><a id="qemu">/etc/libvirt/hooks/qemu</a></h5>
- <ul>
- <li>Before a QEMU guest is started, the qemu hook script is
- called in three locations; if any location fails, the guest
- is not started. The first location, <span class="since">since
- 0.9.0</span>, is before libvirt performs any resource
- labeling, and the hook can allocate resources not managed by
- libvirt such as DRBD or missing bridges. This is called as:<br/>
- <pre>/etc/libvirt/hooks/qemu guest_name prepare begin -</pre>
- The second location, available <span class="since">Since
- 0.8.0</span>, occurs after libvirt has finished labeling
- all resources, but has not yet started the guest, called as:<br/>
- <pre>/etc/libvirt/hooks/qemu guest_name start begin -</pre>
- The third location, <span class="since">0.9.13</span>,
- occurs after the QEMU process has successfully started up:<br/>
- <pre>/etc/libvirt/hooks/qemu guest_name started begin -</pre>
- </li>
- <li>When a QEMU guest is stopped, the qemu hook script is called
- in two locations, to match the startup.
- First, <span class="since">since 0.8.0</span>, the hook is
- called before libvirt restores any labels:<br/>
- <pre>/etc/libvirt/hooks/qemu guest_name stopped end -</pre>
- Then, after libvirt has released all resources, the hook is
- called again, <span class="since">since 0.9.0</span>, to
allow
- any additional resource cleanup:<br/>
- <pre>/etc/libvirt/hooks/qemu guest_name release end
-</pre></li>
- <li><span class="since">Since 0.9.11</span>, the qemu
hook script
- is also called at the beginning of incoming migration. It is called
- as: <pre>/etc/libvirt/hooks/qemu guest_name migrate begin -</pre>
- with domain XML sent to standard input of the script. In this case,
- the script acts as a filter and is supposed to modify the domain
- XML and print it out on its standard output. Empty output is
- identical to copying the input XML without changing it. In case the
- script returns failure or the output XML is not valid, incoming
- migration will be canceled. This hook may be used, e.g., to change
- location of disk images for incoming domains.</li>
- <li><span class="since">Since 1.2.9</span>, the qemu
hook script is
- also called when restoring a saved image either via the API or
- automatically when restoring a managed save machine. It is called
- as: <pre>/etc/libvirt/hooks/qemu guest_name restore begin -</pre>
- with domain XML sent to standard input of the script. In this case,
- the script acts as a filter and is supposed to modify the domain
- XML and print it out on its standard output. Empty output is
- identical to copying the input XML without changing it. In case the
- script returns failure or the output XML is not valid, restore of the
- image will be aborted. This hook may be used, e.g., to change
- location of disk images for restored domains.</li>
- <li><span class="since">Since 6.5.0</span>, you can
also place several
- hook scripts in the directory
- <code>/etc/libvirt/hooks/qemu.d/</code>. They are executed in
- alphabetical order after main script. In this case each script also
- acts as filter and can modify the domain XML and print it out on
- its standard output. This script output is passed to standard input
- next script in order. Empty output from any script is also identical
- to copying the input XML without changing it.
- In case any script returns failure common process will be aborted,
- but all scripts from the directory will are executed.</li>
- <li><span class="since">Since 0.9.13</span>, the qemu
hook script
- is also called when the libvirtd daemon restarts and reconnects
- to previously running QEMU processes. If the script fails, the
- existing QEMU process will be killed off. It is called as:
- <pre>/etc/libvirt/hooks/qemu guest_name reconnect begin -</pre>
- </li>
- <li><span class="since">Since 0.9.13</span>, the qemu
hook script
- is also called when the QEMU driver is told to attach to an
- externally launched QEMU process. It is called as:
- <pre>/etc/libvirt/hooks/qemu guest_name attach begin -</pre>
- </li>
- </ul>
-
- <h5><a id="lxc">/etc/libvirt/hooks/lxc</a></h5>
- <ul>
- <li>Before a LXC guest is started, the lxc hook script is
- called in three locations; if any location fails, the guest
- is not started. The first location, <span class="since">since
- 0.9.13</span>, is before libvirt performs any resource
- labeling, and the hook can allocate resources not managed by
- libvirt such as DRBD or missing bridges. This is called as:<br/>
- <pre>/etc/libvirt/hooks/lxc guest_name prepare begin -</pre>
- The second location, available <span class="since">Since
- 0.8.0</span>, occurs after libvirt has finished labeling
- all resources, but has not yet started the guest, called as:<br/>
- <pre>/etc/libvirt/hooks/lxc guest_name start begin -</pre>
- The third location, <span class="since">0.9.13</span>,
- occurs after the LXC process has successfully started up:<br/>
- <pre>/etc/libvirt/hooks/lxc guest_name started begin -</pre>
- </li>
- <li>When a LXC guest is stopped, the lxc hook script is called
- in two locations, to match the startup.
- First, <span class="since">since 0.8.0</span>, the hook is
- called before libvirt restores any labels:<br/>
- <pre>/etc/libvirt/hooks/lxc guest_name stopped end -</pre>
- Then, after libvirt has released all resources, the hook is
- called again, <span class="since">since 0.9.0</span>, to
allow
- any additional resource cleanup:<br/>
- <pre>/etc/libvirt/hooks/lxc guest_name release end
-</pre></li>
- <li><span class="since">Since 0.9.13</span>, the lxc
hook script
- is also called when the libvirtd daemon restarts and reconnects
- to previously running LXC processes. If the script fails, the
- existing LXC process will be killed off. It is called as:
- <pre>/etc/libvirt/hooks/lxc guest_name reconnect begin -</pre>
- </li>
- </ul>
-
- <h5><a
id="libxl">/etc/libvirt/hooks/libxl</a></h5>
- <ul>
- <li>Before a Xen guest is started using libxl driver, the libxl hook
- script is called in three locations; if any location fails, the guest
- is not started. The first location, <span class="since">since
- 2.1.0</span>, is before libvirt performs any resource
- labeling, and the hook can allocate resources not managed by
- libvirt. This is called as:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name prepare begin -</pre>
- The second location, available <span class="since">Since
- 2.1.0</span>, occurs after libvirt has finished labeling
- all resources, but has not yet started the guest, called as:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name start begin -</pre>
- The third location, <span class="since">2.1.0</span>,
- occurs after the domain has successfully started up:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name started begin -</pre>
- </li>
- <li>When a libxl-handled Xen guest is stopped, the libxl hook script
- is called in two locations, to match the startup.
- First, <span class="since">since 2.1.0</span>, the hook is
- called before libvirt restores any labels:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name stopped end -</pre>
- Then, after libvirt has released all resources, the hook is
- called again, <span class="since">since 2.1.0</span>, to
allow
- any additional resource cleanup:<br/>
- <pre>/etc/libvirt/hooks/libxl guest_name release end
-</pre></li>
- <li><span class="since">Since 2.1.0</span>, the libxl
hook script
- is also called at the beginning of incoming migration. It is called
- as: <pre>/etc/libvirt/hooks/libxl guest_name migrate begin -</pre>
- with domain XML sent to standard input of the script. In this case,
- the script acts as a filter and is supposed to modify the domain
- XML and print it out on its standard output. Empty output is
- identical to copying the input XML without changing it. In case the
- script returns failure or the output XML is not valid, incoming
- migration will be canceled. This hook may be used, e.g., to change
- location of disk images for incoming domains.</li>
- <li><span class="since">Since 6.5.0</span>, you can
also place several
- hook scripts in the directory
- <code>/etc/libvirt/hooks/libxl.d/</code>. They are executed in
- alphabetical order after main script. In this case each script also
- acts as filter and can modify the domain XML and print it out on
- its standard output. This script output is passed to standard input
- next script in order. Empty output from any script is also identical
- to copying the input XML without changing it.
- In case any script returns failure common process will be aborted,
- but all scripts from the directory will are executed.</li>
- <li><span class="since">Since 2.1.0</span>, the libxl
hook script
- is also called when the libvirtd daemon restarts and reconnects
- to previously running Xen domains. If the script fails, the
- existing Xen domains will be killed off. It is called as:
- <pre>/etc/libvirt/hooks/libxl guest_name reconnect begin -</pre>
- </li>
- </ul>
-
- <h5><a
id="network">/etc/libvirt/hooks/network</a></h5>
- <ul>
- <li><span class="since">Since 1.2.2</span>, before a
network is started,
- this script is called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name start begin
-</pre></li>
- <li>After the network is started, up & running, the script is
- called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name started begin
-</pre></li>
- <li>When a network is shut down, this script is called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name stopped end
-</pre></li>
- <li>Later, when network is started and there's an interface from a
- domain to be plugged into the network, the hook script is called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name port-created begin
-</pre>
- Please note, that in this case, the script is passed both network and
- port XMLs on its stdin.</li>
- <li>When network is updated, the hook script is called as:<br/>
- <pre>/etc/libvirt/hooks/network network_name updated begin
-</pre></li>
- <li>When the domain from previous case is shutting down, the interface
- is unplugged. This leads to another script invocation:<br/>
- <pre>/etc/libvirt/hooks/network network_name port-deleted begin
-</pre>
- And again, as in previous case, both network and port XMLs are passed
- onto script's stdin.</li>
- </ul>
-
- <br/>
-
- <h2><a id="execution">Script execution</a></h2>
- <ul>
- <li>The "start" operation for the guest and network hook scripts,
- executes <b>prior</b> to the object (guest or network) being
created.
- This allows the object start operation to be aborted if the script
- returns indicating failure.<br/><br/></li>
- <li>The "stopped" operation for the guest and network hook
scripts,
- executes <b>after</b> the object (guest or network) has stopped.
If
- the hook script indicates failure in its return, the shut down of the
- object cannot be aborted because it has already been performed.
- <br/><br/></li>
- <li>Hook scripts execute in a synchronous fashion. Libvirt waits
- for them to return before continuing the given
operation.<br/><br/>
- This is most noticeable with the guest or network start operation,
- as a lengthy operation in the hook script can mean an extended wait
- for the guest or network to be available to end
users.<br/><br/></li>
- <li>For a hook script to be utilised, it must have its execute bit set
- (e.g. chmod o+rx <i>qemu</i>), and must be present when the
libvirt
- daemon is started.<br/><br/></li>
- <li>If a hook script is added to a host after the libvirt daemon is
- already running, it won't be used until the libvirt daemon
- next starts.</li>
- </ul>
- <br/>
-
- <h2><a id="qemu_migration">QEMU guest
migration</a></h2>
- <p>Migration of a QEMU guest involves running hook scripts on both the
- source and destination hosts:</p>
- <ol>
- <li>At the beginning of the migration, the <i>qemu</i> hook
script on
- the <b>destination</b> host is executed with the
"migrate"
- operation.</li>
- <li>Before QEMU process is spawned, the two operations ("prepare"
and
- "start") called for domain start are executed on
- <b>destination</b> host.</li>
- <li>If both of these hook script executions exit successfully (exit
- status 0), the migration continues. Any other exit code indicates
- failure, and the migration is aborted.</li>
- <li>The QEMU guest is then migrated to the destination host.</li>
- <li>Unless an error occurs during the migration process, the
<i>qemu</i>
- hook script on the <b>source</b> host is then executed with the
- "stopped" and "release" operations to indicate it is no
longer
- running on this host. Regardless of the return codes, the
- migration is not aborted as it has already been performed.</li>
- </ol>
- <br/>
-
- <h2><a id="recursive">Calling libvirt functions from within a
hook script</a></h2>
- <p><b>DO NOT DO THIS!</b></p>
- <p>A hook script must not call back into libvirt, as the libvirt daemon
- is already waiting for the script to exit.</p>
- <p>A deadlock is likely to occur.</p>
- <br/>
-
- <h2><a id="return_codes">Return codes and
logging</a></h2>
- <p>If a hook script returns with an exit code of 0, the libvirt daemon
- regards this as successful and performs no logging of it.</p>
- <p>However, if a hook script returns with a non zero exit code, the libvirt
- daemon regards this as a failure, logs its return code, and
- additionally logs anything on stderr the hook script returns.</p>
- <p>For example, a hook script might use this code to indicate failure,
- and send a text string to stderr:</p>
- <pre>echo "Could not find required XYZZY" >&2
-exit 1</pre>
- <p>The resulting entry in the libvirt log will appear as:</p>
- <pre>20:02:40.297: error : virHookCall:285 : Hook script execution failed:
internal error Child process (LC_ALL=C
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
- HOME=/root USER=root LOGNAME=root /etc/libvirt/hooks/qemu qemu
prepare begin -) unexpected exit status 1: Could not find required XYZZY</pre>
- </body>
-</html>
diff --git a/docs/hooks.rst b/docs/hooks.rst
new file mode 100644
index 0000000000..9c5f3ff456
--- /dev/null
+++ b/docs/hooks.rst
@@ -0,0 +1,518 @@
+.. role:: since
+
+====================================
+Hooks for specific system management
+====================================
+
+.. contents::
+
+Custom event scripts
+--------------------
+
+Beginning with libvirt 0.8.0, specific events on a host system will trigger
+custom scripts.
+
+These custom **hook** scripts are executed when any of the following actions
+occur:
+
+- The libvirt daemon starts, stops, or reloads its configuration (
+ :since:`since 0.8.0` )
+- A QEMU guest is started or stopped ( :since:`since 0.8.0` )
+- An LXC guest is started or stopped ( :since:`since 0.8.0` )
+- A libxl-handled Xen guest is started or stopped ( :since:`since 2.1.0` )
+- A network is started or stopped or an interface is plugged/unplugged to/from
+ the network ( :since:`since 1.2.2` )
+
+Script location
+---------------
+
+The libvirt hook scripts are located in the directory
+``$SYSCONFDIR/libvirt/hooks/``.
+
+- In Linux distributions such as Fedora and RHEL, this is
+ ``/etc/libvirt/hooks/``. Other Linux distributions may do this differently.
+- If your installation of libvirt has instead been compiled from source, it is
+ likely to be ``/usr/local/etc/libvirt/hooks/``.
+- :since:`Since 6.5.0` , you can also place several hook scripts in the
+ directories ``/etc/libvirt/hooks/<driver>.d/``.
+
+To use hook scripts, you will need to create this ``hooks`` directory manually,
+place the desired hook scripts inside, then make them executable.
+
+Script names
+------------
+
+At present, there are five hook scripts that can be called:
+
+- ``/etc/libvirt/hooks/daemon``
+ Executed when the libvirt daemon is started, stopped, or reloads its
+ configuration
+- ``/etc/libvirt/hooks/qemu``
+ Executed when a QEMU guest is started, stopped, or migrated
+- ``/etc/libvirt/hooks/lxc``
+ Executed when an LXC guest is started or stopped
+- ``/etc/libvirt/hooks/libxl``
+ Executed when a libxl-handled Xen guest is started, stopped, or migrated
+- ``/etc/libvirt/hooks/network``
+ Executed when a network is started or stopped or an interface is
+ plugged/unplugged to/from the network
+
+:since:`Since 6.5.0` , you can also have several scripts with any name in the
+directories ``/etc/libvirt/hooks/<driver>.d/``. They are executed in
+alphabetical order after main script.
+
+Script structure
+----------------
+
+The hook scripts are executed using standard Linux process creation functions.
+Therefore, they must begin with the declaration of the command interpreter to
+use.
+
+For example:
+
+::
+
+ #!/bin/bash
+
+or:
+
+::
+
+ #!/usr/bin/python
+
+Other command interpreters are equally valid, as is any executable binary, so
+you are welcome to use your favourite languages.
+
+Script arguments
+----------------
+
+The hook scripts are called with specific command line arguments, depending upon
+the script, and the operation being performed.
+
+The guest hook scripts, qemu and lxc, are also given the **full** XML
+description for the domain on their stdin. This includes items such the UUID of
+the domain and its storage information, and is intended to provide all the
+libvirt information the script needs.
+
+For all cases, stdin of the network hook script is provided with the full XML
+description of the network status in the following form:
+
+::
+
+ <hookData>
+ <network>
+ <name>$network_name</name>
+ <uuid>afca425a-2c3a-420c-b2fb-dd7b4950d722</uuid>
+ ...
+ </network>
+ </hookData>
+
+In the case of an network port being created / deleted, the network XML will be
+followed with the full XML description of the port:
+
+::
+
+ <hookData>
+ <network>
+ <name>$network_name</name>
+ <uuid>afca425a-2c3a-420c-b2fb-dd7b4950d722</uuid>
+ ...
+ </network>
+ <networkport>
+ <uuid>5d744f21-ba4a-4d6e-bdb2-30a35ff3207d</uuid>
+ ...
+ <plug type='direct' dev='ens3' mode='vepa'/>
+ </networkport>
+ </hookData>
+
+Please note that this approach is different from other cases such as ``daemon``,
+``qemu`` or ``lxc`` hook scripts, because two XMLs may be passed here, while in
+the other cases only a single XML is passed.
+
+The command line arguments take this approach:
+
+#. The first argument is the name of the **object** involved in the operation,
+ or '-' if there is none.
+ For example, the name of a guest being started.
+#. The second argument is the name of the **operation** being performed.
+ For example, "start" if a guest is being started.
+#. The third argument is a **sub-operation** indication, or '-' if there is
+ none.
+#. The last argument is an **extra argument** string, or '-' if there is none.
+
+Specifics
+~~~~~~~~~
+
+This translates to the following specifics for each hook script:
+
+/etc/libvirt/hooks/daemon
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- | When the libvirt daemon is started, this script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/daemon - start - start
+
+- | When the libvirt daemon is shut down, this script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/daemon - shutdown - shutdown
+
+- | When the libvirt daemon receives the SIGHUP signal, it reloads its
+ configuration and triggers the hook script as:
+
+ ::
+
+ /etc/libvirt/hooks/daemon - reload begin SIGHUP
+
+Please note that when the libvirt daemon is restarted, the *daemon* hook script
+is called once with the "shutdown" operation, and then once with the
"start"
+operation. There is no specific operation to indicate a "restart" is
occurring.
+
+/etc/libvirt/hooks/qemu
+^^^^^^^^^^^^^^^^^^^^^^^
+
+- | Before a QEMU guest is started, the qemu hook script is called in three
+ locations; if any location fails, the guest is not started. The first
+ location, :since:`since 0.9.0` , is before libvirt performs any resource
+ labeling, and the hook can allocate resources not managed by libvirt such
+ as DRBD or missing bridges. This is called as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name prepare begin -
+
+ | The second location, available :since:`Since 0.8.0` , occurs after libvirt
+ has finished labeling all resources, but has not yet started the guest,
+ called as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name start begin -
+
+ | The third location, :since:`0.9.13` , occurs after the QEMU process has
+ successfully started up:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name started begin -
+
+- | When a QEMU guest is stopped, the qemu hook script is called in two
+ locations, to match the startup. First, :since:`since 0.8.0` , the hook is
+ called before libvirt restores any labels:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name stopped end -
+
+ | Then, after libvirt has released all resources, the hook is called again,
+ :since:`since 0.9.0` , to allow any additional resource cleanup:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name release end -
+
+- :since:`Since 0.9.11` , the qemu hook script is also called at the beginning
+ of incoming migration. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name migrate begin -
+
+ with domain XML sent to standard input of the script. In this case, the
+ script acts as a filter and is supposed to modify the domain XML and print it
+ out on its standard output. Empty output is identical to copying the input
+ XML without changing it. In case the script returns failure or the output XML
+ is not valid, incoming migration will be canceled. This hook may be used,
+ e.g., to change location of disk images for incoming domains.
+
+- :since:`Since 1.2.9` , the qemu hook script is also called when restoring a
+ saved image either via the API or automatically when restoring a managed save
+ machine. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name restore begin -
+
+ with domain XML sent to standard input of the script. In this case, the
+ script acts as a filter and is supposed to modify the domain XML and print it
+ out on its standard output. Empty output is identical to copying the input
+ XML without changing it. In case the script returns failure or the output XML
+ is not valid, restore of the image will be aborted. This hook may be used,
+ e.g., to change location of disk images for restored domains.
+
+- :since:`Since 6.5.0` , you can also place several hook scripts in the
+ directory ``/etc/libvirt/hooks/qemu.d/``. They are executed in alphabetical
+ order after main script. In this case each script also acts as filter and can
+ modify the domain XML and print it out on its standard output. This script
+ output is passed to standard input next script in order. Empty output from
+ any script is also identical to copying the input XML without changing it. In
+ case any script returns failure common process will be aborted, but all
+ scripts from the directory will are executed.
+
+- :since:`Since 0.9.13` , the qemu hook script is also called when the libvirtd
+ daemon restarts and reconnects to previously running QEMU processes. If the
+ script fails, the existing QEMU process will be killed off. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name reconnect begin -
+
+- :since:`Since 0.9.13` , the qemu hook script is also called when the QEMU
+ driver is told to attach to an externally launched QEMU process. It is called
+ as:
+
+ ::
+
+ /etc/libvirt/hooks/qemu guest_name attach begin -
+
+/etc/libvirt/hooks/lxc
+^^^^^^^^^^^^^^^^^^^^^^
+
+- | Before a LXC guest is started, the lxc hook script is called in three
+ locations; if any location fails, the guest is not started. The first
+ location, :since:`since 0.9.13` , is before libvirt performs any resource
+ labeling, and the hook can allocate resources not managed by libvirt such
+ as DRBD or missing bridges. This is called as:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name prepare begin -
+
+ | The second location, available :since:`Since 0.8.0` , occurs after libvirt
+ has finished labeling all resources, but has not yet started the guest,
+ called as:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name start begin -
+
+ | The third location, :since:`0.9.13` , occurs after the LXC process has
+ successfully started up:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name started begin -
+
+- | When a LXC guest is stopped, the lxc hook script is called in two
+ locations, to match the startup. First, :since:`since 0.8.0` , the hook is
+ called before libvirt restores any labels:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name stopped end -
+
+ | Then, after libvirt has released all resources, the hook is called again,
+ :since:`since 0.9.0` , to allow any additional resource cleanup:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name release end -
+
+- :since:`Since 0.9.13` , the lxc hook script is also called when the libvirtd
+ daemon restarts and reconnects to previously running LXC processes. If the
+ script fails, the existing LXC process will be killed off. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/lxc guest_name reconnect begin -
+
+/etc/libvirt/hooks/libxl
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+- | Before a Xen guest is started using libxl driver, the libxl hook script is
+ called in three locations; if any location fails, the guest is not started.
+ The first location, :since:`since 2.1.0` , is before libvirt performs any
+ resource labeling, and the hook can allocate resources not managed by
+ libvirt. This is called as:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name prepare begin -
+
+ | The second location, available :since:`Since 2.1.0` , occurs after libvirt
+ has finished labeling all resources, but has not yet started the guest,
+ called as:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name start begin -
+
+ | The third location, :since:`2.1.0` , occurs after the domain has
+ successfully started up:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name started begin -
+
+- | When a libxl-handled Xen guest is stopped, the libxl hook script is called
+ in two locations, to match the startup. First, :since:`since 2.1.0` , the
+ hook is called before libvirt restores any labels:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name stopped end -
+
+ | Then, after libvirt has released all resources, the hook is called again,
+ :since:`since 2.1.0` , to allow any additional resource cleanup:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name release end -
+
+- :since:`Since 2.1.0` , the libxl hook script is also called at the beginning
+ of incoming migration. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name migrate begin -
+
+ with domain XML sent to standard input of the script. In this case, the
+ script acts as a filter and is supposed to modify the domain XML and print it
+ out on its standard output. Empty output is identical to copying the input
+ XML without changing it. In case the script returns failure or the output XML
+ is not valid, incoming migration will be canceled. This hook may be used,
+ e.g., to change location of disk images for incoming domains.
+
+- :since:`Since 6.5.0` , you can also place several hook scripts in the
+ directory ``/etc/libvirt/hooks/libxl.d/``. They are executed in alphabetical
+ order after main script. In this case each script also acts as filter and can
+ modify the domain XML and print it out on its standard output. This script
+ output is passed to standard input next script in order. Empty output from
+ any script is also identical to copying the input XML without changing it. In
+ case any script returns failure common process will be aborted, but all
+ scripts from the directory will are executed.
+
+- :since:`Since 2.1.0` , the libxl hook script is also called when the libvirtd
+ daemon restarts and reconnects to previously running Xen domains. If the
+ script fails, the existing Xen domains will be killed off. It is called as:
+
+ ::
+
+ /etc/libvirt/hooks/libxl guest_name reconnect begin -
+
+/etc/libvirt/hooks/network
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- | :since:`Since 1.2.2` , before a network is started, this script is called
+ as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name start begin -
+
+- | After the network is started, up & running, the script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name started begin -
+
+- | When a network is shut down, this script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name stopped end -
+
+- | Later, when network is started and there's an interface from a domain to be
+ plugged into the network, the hook script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name port-created begin -
+
+ Please note, that in this case, the script is passed both network and port
+ XMLs on its stdin.
+
+- | When network is updated, the hook script is called as:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name updated begin -
+
+- | When the domain from previous case is shutting down, the interface is
+ unplugged. This leads to another script invocation:
+
+ ::
+
+ /etc/libvirt/hooks/network network_name port-deleted begin -
+
+ And again, as in previous case, both network and port XMLs are passed onto
+ script's stdin.
+
+Script execution
+----------------
+
+- The "start" operation for the guest and network hook scripts, executes
+ **prior** to the object (guest or network) being created. This allows the
+ object start operation to be aborted if the script returns indicating
+ failure.
+- The "stopped" operation for the guest and network hook scripts, executes
+ **after** the object (guest or network) has stopped. If the hook script
+ indicates failure in its return, the shut down of the object cannot be
+ aborted because it has already been performed.
+- Hook scripts execute in a synchronous fashion. Libvirt waits for them to
+ return before continuing the given operation.
+ This is most noticeable with the guest or network start operation, as a
+ lengthy operation in the hook script can mean an extended wait for the guest
+ or network to be available to end users.
+- For a hook script to be utilised, it must have its execute bit set (e.g.
+ chmod o+rx *qemu*), and must be present when the libvirt daemon is started.
+- If a hook script is added to a host after the libvirt daemon is already
+ running, it won't be used until the libvirt daemon next starts.
+
+QEMU guest migration
+--------------------
+
+Migration of a QEMU guest involves running hook scripts on both the source and
+destination hosts:
+
+#. At the beginning of the migration, the *qemu* hook script on the
+ **destination** host is executed with the "migrate" operation.
+#. Before QEMU process is spawned, the two operations ("prepare" and
"start")
+ called for domain start are executed on **destination** host.
+#. If both of these hook script executions exit successfully (exit status 0),
+ the migration continues. Any other exit code indicates failure, and the
+ migration is aborted.
+#. The QEMU guest is then migrated to the destination host.
+#. Unless an error occurs during the migration process, the *qemu* hook script
+ on the **source** host is then executed with the "stopped" and
"release"
+ operations to indicate it is no longer running on this host. Regardless of
+ the return codes, the migration is not aborted as it has already been
+ performed.
+
+Calling libvirt functions from within a hook script
+---------------------------------------------------
+
+**DO NOT DO THIS!**
+
+A hook script must not call back into libvirt, as the libvirt daemon is already
+waiting for the script to exit.
+
+A deadlock is likely to occur.
+
+Return codes and logging
+------------------------
+
+If a hook script returns with an exit code of 0, the libvirt daemon regards this
+as successful and performs no logging of it.
+
+However, if a hook script returns with a non zero exit code, the libvirt daemon
+regards this as a failure, logs its return code, and additionally logs anything
+on stderr the hook script returns.
+
+For example, a hook script might use this code to indicate failure, and send a
+text string to stderr:
+
+::
+
+ echo "Could not find required XYZZY" >&2
+ exit 1
+
+The resulting entry in the libvirt log will appear as:
+
+::
+
+ 20:02:40.297: error : virHookCall:285 : Hook script execution failed: internal error
Child process (LC_ALL=C PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+ HOME=/root USER=root LOGNAME=root /etc/libvirt/hooks/qemu qemu
prepare begin -) unexpected exit status 1: Could not find required XYZZY
diff --git a/docs/meson.build b/docs/meson.build
index 22eca7d8bd..a0e96e2453 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -25,7 +25,6 @@ docs_html_in_files = [
'formatnetwork',
'formatnode',
'formatnwfilter',
- 'hooks',
'index',
'internals',
'java',
@@ -92,6 +91,7 @@ docs_rst_files = [
'goals',
'governance',
'hacking',
+ 'hooks',
'libvirt-go',
'libvirt-go-xml',
'macos',
--
2.35.1
7:10 a.m.
New subject: [PATCH 26/29] docs: Convert 'java' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/java.html.in | 121 -------------------------------------------
docs/java.rst | 128 ++++++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 129 insertions(+), 122 deletions(-)
delete mode 100644 docs/java.html.in
create mode 100644 docs/java.rst
diff --git a/docs/java.html.in b/docs/java.html.in
deleted file mode 100644
index 1f8c255d26..0000000000
--- a/docs/java.html.in
+++ /dev/null
@@ -1,121 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Java API bindings</h1>
-
-<h2>Presentation</h2>
- <p>The Java bindings make use of <a
href="https://jna.dev.java.net/">JNA</a>
- to expose the C API in a Java friendly way. The bindings are based on
- work initiated by Toth Istvan.</p>
-
-<h2>Getting it</h2>
-<p>
- The latest versions of the libvirt Java bindings can be downloaded from:
-</p>
-
-<ul>
-<li><a href="ftp://libvirt.org/libvirt/java/">libvirt.org FTP
server</a></li>
-<li><a href="https://libvirt.org/sources/java/">libvirt.org HTTP
server</a></li>
-</ul>
-
-<h3>Maven</h3>
-<p>A maven repository is located at <a
href="https://libvirt.org/maven2/">https://libvirt.org/maven...
-which you can use to include this in your maven projects.</p>
-
-<h2>GIT source repository</h2>
-<p> The Java bindings code source is now maintained in a <a
-href="https://git-scm.com/">git</a> repository available on
-<a href="https://gitlab.com/libvirt/libvirt-java/">gitlab.com&l...;:
-</p>
-<pre>
-git clone https://gitlab.com/libvirt/libvirt-java.git
-</pre>
-
-<h2>Building</h2>
-<p>The code is built using ant, and assumes that you have the jna jar installed.
Once you have downloaded
-the code you can build the code with</p>
-
-<pre>
-
-% cd libvirt-java
-% ant build
-</pre>
-
-
-<h2>Content</h2>
-<p>The bindings are articulated around a few
-classes in the <code>org/libvirt</code> package, notably the
-<code>Connect</code>, <code>Domain</code> and
<code>Network</code>
-ones. Functions in the <a href="html/index.html">C API</a>
-taking <code>virConnectPtr</code>, <code>virDomainPtr</code> or
-<code>virNetworkPtr</code> as their first argument usually become
-methods for the classes, their name is just stripped from the
-virConnect or virDomain(Get) prefix and the first letter gets converted to
-lower case, for example the C functions:</p>
- <p>
- <code>int <a
href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains">virConnectNumOfDomains</a>
-(virConnectPtr conn);</code>
- </p>
- <p>
- <code>int <a
href="html/libvirt-libvirt-domain.html#virDomainSetMaxMemory">virDomainSetMaxMemory</a>
-(virDomainPtr domain, unsigned long memory);</code>
- </p>
- <p>become</p>
- <p>
- <code>virConn.numOfDomains()</code>
- </p>
- <p>
- <code>virDomain.setMaxMemory(long memory)</code>
- </p>
- <p> There is of course some functions where the mapping is less direct
-and using extra classes to map complex arguments. The <a
href="https://libvirt.org/sources/java/javadoc">Javadoc</... is
available online or as
-part of a separate libvirt-java-javadoc package.</p>
- <p>So let's look at a simple example inspired from the
-<code>test.java</code> test found in <code>src</code> in the
source tree:</p>
- <pre>import <span style="color: #0071FF; background-color:
#FFFFFF">org.libvirt.*</span>;
-public class minitest {
- public static void main(String[] args) {
- Connect conn=null;
- try{
- conn = new <span style="color: #0071FF; background-color:
#FFFFFF">Connect</span>("test:///default", true);
- } catch (<span style="color: #0071FF; background-color:
#FFFFFF">LibvirtException</span> e) {
- System.out.println("exception caught:"+e);
- System.out.println(e.getError());
- }
- try{
- <span style="color: #0071FF; background-color:
#FFFFFF">Domain</span> testDomain=conn.<span style="color: #007F00;
background-color: #FFFFFF">domainLookupByName</span>("test");
- System.out.println("Domain:" + testDomain.<span
style="color: #E50073; background-color: #FFFFFF">getName</span>() +
" id " +
- testDomain.<span style="color: #E50073;
background-color: #FFFFFF">getID</span>() + " running " +
- testDomain.<span style="color: #E50073;
background-color: #FFFFFF">getOSType</span>());
- } catch (<span style="color: #0071FF; background-color:
#FFFFFF">LibvirtException</span> e) {
- System.out.println("exception caught:"+e);
- System.out.println(e.getError());
- }
- }
-}
-</pre>
- <p>There is not much to comment about it, it really is a straight mapping
-from the C API, the only points to notice are:</p>
- <ul>
- <li>the import of the modules in the <code><span style="color:
#0071FF; background-color: #FFFFFF">org.libvirt</span></code>
package</li>
- <li>getting a connection to the hypervisor, in that case using the
- readonly access to the default test hypervisor.</li>
- <li>getting an object representing the test domain using <span
style="color: #007F00; background-color:
#FFFFFF">lookupByName</span></li>
- <li>if the domain is not found a LibvirtError exception will be
raised</li>
- <li>extracting and printing some information about the domain using
- various <span style="color: #E50073; background-color:
#FFFFFF">methods</span>
- associated to the Domain class.</li>
- </ul>
-<h2>Maven</h2>
- <p>Up until version 0.4.7 the Java bindings were available from the central maven
repository.</p>
- <p>If you want to use 0.4.8 or higher, please add the following repository to
your pom.xml</p>
- <pre><repositories>
- <repository>
- <id>libvirt-org</id>
- <url>https://libvirt.org/maven2</url>
- </repository>
-</repositories></pre>
-
- </body>
-</html>
diff --git a/docs/java.rst b/docs/java.rst
new file mode 100644
index 0000000000..df846c6fc6
--- /dev/null
+++ b/docs/java.rst
@@ -0,0 +1,128 @@
+=================
+Java API bindings
+=================
+
+.. contents::
+
+Presentation
+------------
+
+The Java bindings make use of `JNA <https://jna.dev.java.net/>`__ to expose the
+C API in a Java friendly way. The bindings are based on work initiated by Toth
+Istvan.
+
+Getting it
+----------
+
+The latest versions of the libvirt Java bindings can be downloaded from:
+
+- `libvirt.org FTP server <ftp://libvirt.org/libvirt/java/>`__
+- `libvirt.org HTTP server <https://libvirt.org/sources/java/>`__
+
+A maven repository is located at https://libvirt.org/maven2/ which you can use
+to include this in your maven projects.
+
+GIT source repository
+---------------------
+
+The Java bindings code source is now maintained in a
+`git <https://git-scm.com/>`__ repository available on
+`gitlab.com <https://gitlab.com/libvirt/libvirt-java/>`__:
+
+::
+
+ git clone https://gitlab.com/libvirt/libvirt-java.git
+
+Building
+--------
+
+The code is built using ant, and assumes that you have the jna jar installed.
+Once you have downloaded the code you can build the code with
+
+::
+
+
+ % cd libvirt-java
+ % ant build
+
+Content
+-------
+
+The bindings are articulated around a few classes in the ``org/libvirt``
+package, notably the ``Connect``, ``Domain`` and ``Network`` ones. Functions in
+the `C API <html/index.html>`__ taking ``virConnectPtr``, ``virDomainPtr`` or
+``virNetworkPtr`` as their first argument usually become methods for the
+classes, their name is just stripped from the virConnect or virDomain(Get)
+prefix and the first letter gets converted to lower case, for example the C
+functions:
+
+``int virConnectNumOfDomains (virConnectPtr conn);``
+
+``int virDomainSetMaxMemory (virDomainPtr domain, unsigned long memory);``
+
+become
+
+``virConn.numOfDomains()``
+
+``virDomain.setMaxMemory(long memory)``
+
+There is of course some functions where the mapping is less direct and using
+extra classes to map complex arguments. The
+`Javadoc <https://libvirt.org/sources/java/javadoc>`__ is available online or as
+part of a separate libvirt-java-javadoc package.
+
+So let's look at a simple example inspired from the ``test.java`` test found in
+``src`` in the source tree:
+
+::
+
+ import org.libvirt.*;
+ public class minitest {
+ public static void main(String[] args) {
+ Connect conn=null;
+ try{
+ conn = new Connect("test:///default", true);
+ } catch (LibvirtException e) {
+ System.out.println("exception caught:"+e);
+ System.out.println(e.getError());
+ }
+ try{
+ Domain testDomain=conn.domainLookupByName("test");
+ System.out.println("Domain:" + testDomain.getName() + " id
" +
+ testDomain.getID() + " running " +
+ testDomain.getOSType());
+ } catch (LibvirtException e) {
+ System.out.println("exception caught:"+e);
+ System.out.println(e.getError());
+ }
+ }
+ }
+
+There is not much to comment about it, it really is a straight mapping from the
+C API, the only points to notice are:
+
+- the import of the modules in the ``org.libvirt`` package
+- getting a connection to the hypervisor, in that case using the readonly
+ access to the default test hypervisor.
+- getting an object representing the test domain using ``lookupByName``
+- if the domain is not found a LibvirtError exception will be raised
+- extracting and printing some information about the domain using various
+ methods associated to the Domain class.
+
+Maven
+-----
+
+Up until version 0.4.7 the Java bindings were available from the central maven
+repository.
+
+If you want to use 0.4.8 or higher, please add the following repository to your
+pom.xml
+
+::
+
+ <repositories>
+ <repository>
+ <id>libvirt-org</id>
+ <url>https://libvirt.org/maven2</url>
+ </repository>
+ </repositories>
diff --git a/docs/meson.build b/docs/meson.build
index a0e96e2453..e1b618438c 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -27,7 +27,6 @@ docs_html_in_files = [
'formatnwfilter',
'index',
'internals',
- 'java',
'logging',
'php',
'python',
@@ -92,6 +91,7 @@ docs_rst_files = [
'governance',
'hacking',
'hooks',
+ 'java',
'libvirt-go',
'libvirt-go-xml',
'macos',
--
2.35.1
8:48 a.m.
New subject: [PATCH 26/29] docs: Convert 'java' page to rST
On Mon, Mar 28, 2022 at 02:10:41PM +0200, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
...
-<h2>Maven</h2>
- <p>Up until version 0.4.7 the Java bindings were available from the central
maven repository.</p>
- <p>If you want to use 0.4.8 or higher, please add the following repository to
your pom.xml</p>
- <pre><repositories>
- <repository>
- <id>libvirt-org</id>
- <url>https://libvirt.org/maven2 </url>
Have you tuned this by hand? ^This extra space causes another
merge conflict.
The rest is fine:
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 a.m.
New subject: [PATCH 27/29] docs: Convert 'logging' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/logging.html.in | 243 -------------------------------------------
docs/logging.rst | 243 +++++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 244 insertions(+), 244 deletions(-)
delete mode 100644 docs/logging.html.in
create mode 100644 docs/logging.rst
diff --git a/docs/logging.html.in b/docs/logging.html.in
deleted file mode 100644
index 1052b763a0..0000000000
--- a/docs/logging.html.in
+++ /dev/null
@@ -1,243 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1 >Logging in the library and the daemon</h1>
-
- <p>Libvirt includes logging facilities starting from version 0.6.0,
- this complements the <a href="errors.html">error
handling</a>
- mechanism and APIs to allow tracing through the execution of the
- library as well as in the libvirtd daemon.</p>
-
- <ul id="toc"/>
-
- <h2>
- <a id="log_library">Logging in the library</a>
- </h2>
- <p>The logging functionalities in libvirt are based on 3 key concepts,
- similar to the one present in other generic logging facilities like
- log4j:</p>
- <ul>
- <li><b>log messages</b>: they are information generated at
runtime by
- the libvirt code. Each message includes a priority level (DEBUG = 1,
- INFO = 2, WARNING = 3, ERROR = 4), a category, function name and
- line number, indicating where it originated from, and finally
- a formatted message. In addition the library adds a timestamp
- at the beginning of the message</li>
- <li><b>log filters</b>: a set of patterns and priorities to
accept
- or reject a log message. If the message category matches a filter,
- the message priority is compared to the filter priority, if lower
- the message is discarded, if higher the message is output. If
- no filter matches, then a general priority level is applied to
- all remaining messages. This allows, for example, capturing all
- debug messages for the QEMU driver, but otherwise only allowing
- errors to show up from other parts.</li>
- <li><b>log outputs</b>: once a message has gone through filtering
a set of
- output defines where to send the message, they can also filter
- based on the priority, for example it may be useful to output
- all messages to a debugging file but only allow errors to be
- logged through syslog.</li>
- </ul>
-
- <h2>
- <a id="log_config">Configuring logging in the library</a>
- </h2>
- <p>The library configuration of logging is through 3 environment variables
- allowing to control the logging behaviour:</p>
- <ul>
- <li>LIBVIRT_DEBUG: it can take the four following values:
- <ul>
- <li>1 or "debug": asking the library to log every message
emitted,
- though the filters can be used to avoid filling up the output</li>
- <li>2 or "info": log all non-debugging information</li>
- <li>3 or "warn": log warnings and errors, that's the default
value</li>
- <li>4 or "error": log only error messages</li>
- </ul></li>
- <li>LIBVIRT_LOG_FILTERS: defines logging filters</li>
- <li>LIBVIRT_LOG_OUTPUTS: defines logging outputs</li>
- </ul>
- <p>Note that, for example, setting LIBVIRT_DEBUG= is the same as unset. If
- you specify an invalid value, it will be ignored with a warning. If you
- have an error in a filter or output string, some of the settings may be
- applied up to the point at which libvirt encountered the error.</p>
- <h2>
- <a id="log_daemon">Logging in the daemon</a>
- </h2>
- <p>Similarly the daemon logging behaviour can be tuned using 3 config
- variables, stored in the configuration file:</p>
- <ul>
- <li>log_level: accepts the following values:
- <ul>
- <li>4: only errors</li>
- <li>3: warnings and errors</li>
- <li>2: information, warnings and errors</li>
- <li>1: debug and everything</li>
- </ul></li>
- <li>log_filters: defines logging filters</li>
- <li>log_outputs: defines logging outputs</li>
- </ul>
- <p>When starting the libvirt daemon, any logging environment variable
- settings will override settings in the config file. Command line options
- take precedence over all. If no outputs are defined for libvirtd, it
- will try to use</p>
- <ul>
- <li>0.10.0 or later: systemd journal, if
<code>/run/systemd/journal/socket</code> exists</li>
- <li>0.9.0 or later: file
<code>/var/log/libvirt/libvirtd.log</code> if running as a daemon</li>
- <li>before 0.9.0: syslog if running as a daemon</li>
- <li>all versions: to stderr stream if running in the foreground</li>
- </ul>
- <p>Libvirtd does not reload its logging configuration when issued a SIGHUP.
- If you want to reload the configuration, you must do a <code>service
- libvirtd restart</code> or manually stop and restart the daemon
- yourself.</p>
- <p>Starting from 0.9.0, the daemon can save all the content of the debug
- buffer to the defined error channels (or /var/log/libvirt/libvirtd.log
- by default) in case of crash, this can also be activated explicitly
- for debugging purposes by sending the daemon a USR2 signal:</p>
- <pre>killall -USR2 libvirtd</pre>
- <h2>
- <a id="log_syntax">Syntax for filters and output values</a>
- </h2>
- <p>The syntax for filters and outputs is the same for both types of
- variables.</p>
- <p>The format for a filter is:</p>
- <pre>
-x:name</pre>
- <p>where <code>name</code> is a string which is matched against
- the category given in the VIR_LOG_INIT() at the top of each
- libvirt source file, e.g., <code>remote</code>,
<code>qemu</code>,
- or <code>util.json</code> (the name in the filter can be a
- substring of the full category name, in order to match multiple
- similar categories), and <code>x</code> is the minimal
- level where matching messages should be logged:</p>
- <ul>
- <li>1: DEBUG</li>
- <li>2: INFO</li>
- <li>3: WARNING</li>
- <li>4: ERROR</li>
- </ul>
- <p>Multiple filters can be defined in a single string, they just need to be
- separated by spaces, e.g: <code>"3:remote 4:event"</code> to
only get
- warning or errors from the remote layer and only errors from the event
- layer.</p>
- <p>If you specify a log priority in a filter that is below the default log
- priority level, messages that match that filter will still be logged,
- while others will not. In order to see those messages, you must also have
- an output defined that includes the priority level of your filter.</p>
- <p>The format for an output can be one of the following forms:</p>
- <ul>
- <li><code>x:stderr</code> output goes to stderr</li>
- <li><code>x:syslog:name</code> use syslog for the output and use
the
- given <code>name</code> as the ident</li>
- <li><code>x:file:file_path</code> output to a file, with the
given
- filepath</li>
- <li><code>x:journald</code> output goes to systemd
journal</li>
- </ul>
- <p>In all cases the x prefix is the minimal level, acting as a
filter:</p>
- <ul>
- <li>1: DEBUG</li>
- <li>2: INFO</li>
- <li>3: WARNING</li>
- <li>4: ERROR</li>
- </ul>
- <p>Multiple output can be defined, they just need to be separated by
- spaces, e.g.: <code>"3:syslog:libvirtd
1:file:/tmp/libvirt.log"</code>
- will log all warnings and errors to syslog under the libvirtd ident
- but also log all debug and information included in the
- file <code>/tmp/libvirt.log</code></p>
-
- <h2><a id="journald">Systemd journal
fields</a></h2>
-
- <p>
- When logging to the systemd journal, the following fields
- are defined, in addition to any automatically recorded
- <a
href="https://www.freedesktop.org/software/systemd/man/systemd.journ...
fields</a>:
- </p>
-
- <dl>
- <dt><code>MESSAGE</code></dt>
- <dd>The log message string</dd>
- <dt><code>PRIORITY</code></dt>
- <dd>The log priority value</dd>
- <dt><code>LIBVIRT_SOURCE</code></dt>
- <dd>The source type, one of "file", "error",
"audit", "trace", "library"</dd>
- <dt><code>CODE_FILE</code></dt>
- <dd>The name of the file emitting the log record</dd>
- <dt><code>CODE_LINE</code></dt>
- <dd>The line number of the file emitting the log record</dd>
- <dt><code>CODE_FUNC</code></dt>
- <dd>The name of the function emitting the log record</dd>
- <dt><code>LIBVIRT_DOMAIN</code></dt>
- <dd>The libvirt error domain (values from virErrorDomain enum), if
LIBVIRT_SOURCE="error"</dd>
- <dt><code>LIBVIRT_CODE</code></dt>
- <dd>The libvirt error code (values from virErrorCode enum), if
LIBVIRT_SOURCE="error"</dd>
- </dl>
-
- <h3><a id="journaldids">Well known message ID
values</a></h3>
-
- <p>
- Certain areas of the code will emit log records tagged with well known
- unique id values, which are guaranteed never to change in the future.
- This allows applications to identify critical log events without doing
- string matching on the <code>MESSAGE</code> field.
- </p>
-
- <dl>
-
<dt><code>MESSAGE_ID=8ae2f3fb-2dbe-498e-8fbd-012d40afa361</code></dt>
- <dd>Generated by the QEMU driver when it identifies a QEMU system
- emulator binary, but is unable to extract information about its
- capabilities. This is usually an indicator of a broken QEMU
- build or installation. When this is emitted, the
<code>LIBVIRT_QEMU_BINARY</code>
- message field will provide the full path of the QEMU binary that failed.
- </dd>
- </dl>
-
- <p>
- The <code>journalctl</code> command can be used to search the journal
- matching on specific message ID values
- </p>
-
- <pre>
-$ journalctl MESSAGE_ID=8ae2f3fb-2dbe-498e-8fbd-012d40afa361 --output=json
-{ ...snip...
- "LIBVIRT_SOURCE" : "file",
- "PRIORITY" : "3",
- "CODE_FILE" : "qemu/qemu_capabilities.c",
- "CODE_LINE" : "2770",
- "CODE_FUNC" : "virQEMUCapsLogProbeFailure",
- "MESSAGE_ID" : "8ae2f3fb-2dbe-498e-8fbd-012d40afa361",
- "LIBVIRT_QEMU_BINARY" : "/bin/qemu-system-xtensa",
- "MESSAGE" : "Failed to probe capabilities for
/bin/qemu-system-xtensa:" \
- "internal error: Child process (LC_ALL=C
LD_LIBRARY_PATH=/home/berrange" \
- "/src/virt/libvirt/src/.libs
PATH=/usr/lib64/ccache:/usr/local/sbin:" \
- "/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/root/bin HOME=/root
" \
- "USER=root LOGNAME=root /bin/qemu-system-xtensa -help) unexpected
" \
- "exit status 127: /bin/qemu-system-xtensa: error while loading shared
" \
- "libraries: libglapi.so.0: cannot open shared object file: No such
" \
- "file or directory\n" }
- </pre>
-
- <h2>
- <a id="log_examples">Examples</a>
- </h2>
- <p>For example setting up the following:</p>
- <pre>export LIBVIRT_DEBUG=1
-export LIBVIRT_LOG_OUTPUTS="1:file:virsh.log"</pre>
- <p>and then running virsh will accumulate the logs in the
- <code>virsh.log</code> file in a way similar to:</p>
- <pre>14:29:04.771: debug : virInitialize:278 : register drivers
-14:29:04.771: debug : virRegisterDriver:618 : registering Test as driver 0</pre>
- <p>the messages are timestamped, there is also the level recorded,
- if debug the name of the function is also printed and then the formatted
- message. This should be sufficient to at least get a precise idea of
- what is happening and where things are going wrong, allowing to then
- put the correct breakpoints when running under a debugger.</p>
- <p>To activate full debug of the libvirt entry points, utility
- functions and the QEMU/KVM driver, set:</p>
- <pre>log_filters="1:libvirt 1:util 1:qemu"
-log_outputs="1:file:/var/log/libvirt/libvirtd.log"</pre>
- <p>in libvirtd.conf and restart the daemon will allow to
- gather a copious amount of debugging traces for the operations done
- in those areas.</p>
- </body>
-</html>
diff --git a/docs/logging.rst b/docs/logging.rst
new file mode 100644
index 0000000000..204176c6f5
--- /dev/null
+++ b/docs/logging.rst
@@ -0,0 +1,243 @@
+=====================================
+Logging in the library and the daemon
+=====================================
+
+.. contents::
+
+Libvirt includes logging facilities starting from version 0.6.0, this
+complements the `error handling <errors.html>`__ mechanism and APIs to allow
+tracing through the execution of the library as well as in the libvirtd daemon.
+
+Logging in the library
+----------------------
+
+The logging functionalities in libvirt are based on 3 key concepts, similar to
+the one present in other generic logging facilities like log4j:
+
+- **log messages**: they are information generated at runtime by the libvirt
+ code. Each message includes a priority level (DEBUG = 1, INFO = 2, WARNING =
+ 3, ERROR = 4), a category, function name and line number, indicating where it
+ originated from, and finally a formatted message. In addition the library
+ adds a timestamp at the beginning of the message
+- **log filters**: a set of patterns and priorities to accept or reject a log
+ message. If the message category matches a filter, the message priority is
+ compared to the filter priority, if lower the message is discarded, if higher
+ the message is output. If no filter matches, then a general priority level is
+ applied to all remaining messages. This allows, for example, capturing all
+ debug messages for the QEMU driver, but otherwise only allowing errors to
+ show up from other parts.
+- **log outputs**: once a message has gone through filtering a set of output
+ defines where to send the message, they can also filter based on the
+ priority, for example it may be useful to output all messages to a debugging
+ file but only allow errors to be logged through syslog.
+
+Configuring logging in the library
+----------------------------------
+
+The library configuration of logging is through 3 environment variables allowing
+to control the logging behaviour:
+
+- LIBVIRT_DEBUG: it can take the four following values:
+
+ - 1 or "debug": asking the library to log every message emitted, though
the
+ filters can be used to avoid filling up the output
+ - 2 or "info": log all non-debugging information
+ - 3 or "warn": log warnings and errors, that's the default value
+ - 4 or "error": log only error messages
+
+- LIBVIRT_LOG_FILTERS: defines logging filters
+- LIBVIRT_LOG_OUTPUTS: defines logging outputs
+
+Note that, for example, setting LIBVIRT_DEBUG= is the same as unset. If you
+specify an invalid value, it will be ignored with a warning. If you have an
+error in a filter or output string, some of the settings may be applied up to
+the point at which libvirt encountered the error.
+
+Logging in the daemon
+---------------------
+
+Similarly the daemon logging behaviour can be tuned using 3 config variables,
+stored in the configuration file:
+
+- log_level: accepts the following values:
+
+ - 4: only errors
+ - 3: warnings and errors
+ - 2: information, warnings and errors
+ - 1: debug and everything
+
+- log_filters: defines logging filters
+- log_outputs: defines logging outputs
+
+When starting the libvirt daemon, any logging environment variable settings will
+override settings in the config file. Command line options take precedence over
+all. If no outputs are defined for libvirtd, it will try to use
+
+- 0.10.0 or later: systemd journal, if ``/run/systemd/journal/socket`` exists
+- 0.9.0 or later: file ``/var/log/libvirt/libvirtd.log`` if running as a daemon
+- before 0.9.0: syslog if running as a daemon
+- all versions: to stderr stream if running in the foreground
+
+Libvirtd does not reload its logging configuration when issued a SIGHUP. If you
+want to reload the configuration, you must do a
+``service libvirtd restart`` or manually stop and restart the daemon
+yourself.
+
+Starting from 0.9.0, the daemon can save all the content of the debug buffer to
+the defined error channels (or /var/log/libvirt/libvirtd.log by default) in case
+of crash, this can also be activated explicitly for debugging purposes by
+sending the daemon a USR2 signal:
+
+::
+
+ killall -USR2 libvirtd
+
+Syntax for filters and output values
+------------------------------------
+
+The syntax for filters and outputs is the same for both types of variables.
+
+The format for a filter is:
+
+::
+
+ x:name
+
+where ``name`` is a string which is matched against the category given in the
+VIR_LOG_INIT() at the top of each libvirt source file, e.g., ``remote``,
+``qemu``, or ``util.json`` (the name in the filter can be a substring of the
+full category name, in order to match multiple similar categories), and ``x`` is
+the minimal level where matching messages should be logged:
+
+- 1: DEBUG
+- 2: INFO
+- 3: WARNING
+- 4: ERROR
+
+Multiple filters can be defined in a single string, they just need to be
+separated by spaces, e.g: ``"3:remote 4:event"`` to only get warning or errors
+from the remote layer and only errors from the event layer.
+
+If you specify a log priority in a filter that is below the default log priority
+level, messages that match that filter will still be logged, while others will
+not. In order to see those messages, you must also have an output defined that
+includes the priority level of your filter.
+
+The format for an output can be one of the following forms:
+
+- ``x:stderr`` output goes to stderr
+- ``x:syslog:name`` use syslog for the output and use the given ``name`` as the
+ ident
+- ``x:file:file_path`` output to a file, with the given filepath
+- ``x:journald`` output goes to systemd journal
+
+In all cases the x prefix is the minimal level, acting as a filter:
+
+- 1: DEBUG
+- 2: INFO
+- 3: WARNING
+- 4: ERROR
+
+Multiple output can be defined, they just need to be separated by spaces, e.g.:
+``"3:syslog:libvirtd 1:file:/tmp/libvirt.log"`` will log all warnings and
errors
+to syslog under the libvirtd ident but also log all debug and information
+included in the file ``/tmp/libvirt.log``
+
+Systemd journal fields
+----------------------
+
+When logging to the systemd journal, the following fields are defined, in
+addition to any automatically recorded `standard
+fields
<https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.h...:
+
+``MESSAGE``
+ The log message string
+``PRIORITY``
+ The log priority value
+``LIBVIRT_SOURCE``
+ The source type, one of "file", "error", "audit",
"trace", "library"
+``CODE_FILE``
+ The name of the file emitting the log record
+``CODE_LINE``
+ The line number of the file emitting the log record
+``CODE_FUNC``
+ The name of the function emitting the log record
+``LIBVIRT_DOMAIN``
+ The libvirt error domain (values from virErrorDomain enum), if
+ LIBVIRT_SOURCE="error"
+``LIBVIRT_CODE``
+ The libvirt error code (values from virErrorCode enum), if
+ LIBVIRT_SOURCE="error"
+
+Well known message ID values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Certain areas of the code will emit log records tagged with well known unique id
+values, which are guaranteed never to change in the future. This allows
+applications to identify critical log events without doing string matching on
+the ``MESSAGE`` field.
+
+``MESSAGE_ID=8ae2f3fb-2dbe-498e-8fbd-012d40afa361``
+ Generated by the QEMU driver when it identifies a QEMU system emulator
+ binary, but is unable to extract information about its capabilities. This is
+ usually an indicator of a broken QEMU build or installation. When this is
+ emitted, the ``LIBVIRT_QEMU_BINARY`` message field will provide the full path
+ of the QEMU binary that failed.
+
+The ``journalctl`` command can be used to search the journal matching on
+specific message ID values
+
+::
+
+ $ journalctl MESSAGE_ID=8ae2f3fb-2dbe-498e-8fbd-012d40afa361 --output=json
+ { ...snip...
+ "LIBVIRT_SOURCE" : "file",
+ "PRIORITY" : "3",
+ "CODE_FILE" : "qemu/qemu_capabilities.c",
+ "CODE_LINE" : "2770",
+ "CODE_FUNC" : "virQEMUCapsLogProbeFailure",
+ "MESSAGE_ID" : "8ae2f3fb-2dbe-498e-8fbd-012d40afa361",
+ "LIBVIRT_QEMU_BINARY" : "/bin/qemu-system-xtensa",
+ "MESSAGE" : "Failed to probe capabilities for
/bin/qemu-system-xtensa:" \
+ "internal error: Child process (LC_ALL=C
LD_LIBRARY_PATH=/home/berrange" \
+ "/src/virt/libvirt/src/.libs
PATH=/usr/lib64/ccache:/usr/local/sbin:" \
+ "/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/root/bin HOME=/root
" \
+ "USER=root LOGNAME=root /bin/qemu-system-xtensa -help) unexpected
" \
+ "exit status 127: /bin/qemu-system-xtensa: error while loading
shared " \
+ "libraries: libglapi.so.0: cannot open shared object file: No such
" \
+ "file or directory\n" }
+
+Examples
+--------
+
+For example setting up the following:
+
+::
+
+ export LIBVIRT_DEBUG=1
+ export LIBVIRT_LOG_OUTPUTS="1:file:virsh.log"
+
+and then running virsh will accumulate the logs in the ``virsh.log`` file in a
+way similar to:
+
+::
+
+ 14:29:04.771: debug : virInitialize:278 : register drivers
+ 14:29:04.771: debug : virRegisterDriver:618 : registering Test as driver 0
+
+the messages are timestamped, there is also the level recorded, if debug the
+name of the function is also printed and then the formatted message. This should
+be sufficient to at least get a precise idea of what is happening and where
+things are going wrong, allowing to then put the correct breakpoints when
+running under a debugger.
+
+To activate full debug of the libvirt entry points, utility functions and the
+QEMU/KVM driver, set:
+
+::
+
+ log_filters="1:libvirt 1:util 1:qemu"
+ log_outputs="1:file:/var/log/libvirt/libvirtd.log"
+
+in libvirtd.conf and restart the daemon will allow to gather a copious amount of
+debugging traces for the operations done in those areas.
diff --git a/docs/meson.build b/docs/meson.build
index e1b618438c..f6e51353f0 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -27,7 +27,6 @@ docs_html_in_files = [
'formatnwfilter',
'index',
'internals',
- 'logging',
'php',
'python',
'remote',
@@ -94,6 +93,7 @@ docs_rst_files = [
'java',
'libvirt-go',
'libvirt-go-xml',
+ 'logging',
'macos',
'migration',
'newreposetup',
--
2.35.1
7:10 a.m.
New subject: [PATCH 28/29] docs: logging: Replace example by link to kbase/debuglogs.html
The 'debuglogs' knowledge base page has way more info and examples on
how to set logging use it instead of the ad-hoc examples.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/logging.rst | 34 +++-------------------------------
1 file changed, 3 insertions(+), 31 deletions(-)
diff --git a/docs/logging.rst b/docs/logging.rst
index 204176c6f5..c7c14504ae 100644
--- a/docs/logging.rst
+++ b/docs/logging.rst
@@ -210,34 +210,6 @@ specific message ID values
Examples
--------
-For example setting up the following:
-
-::
-
- export LIBVIRT_DEBUG=1
- export LIBVIRT_LOG_OUTPUTS="1:file:virsh.log"
-
-and then running virsh will accumulate the logs in the ``virsh.log`` file in a
-way similar to:
-
-::
-
- 14:29:04.771: debug : virInitialize:278 : register drivers
- 14:29:04.771: debug : virRegisterDriver:618 : registering Test as driver 0
-
-the messages are timestamped, there is also the level recorded, if debug the
-name of the function is also printed and then the formatted message. This should
-be sufficient to at least get a precise idea of what is happening and where
-things are going wrong, allowing to then put the correct breakpoints when
-running under a debugger.
-
-To activate full debug of the libvirt entry points, utility functions and the
-QEMU/KVM driver, set:
-
-::
-
- log_filters="1:libvirt 1:util 1:qemu"
- log_outputs="1:file:/var/log/libvirt/libvirtd.log"
-
-in libvirtd.conf and restart the daemon will allow to gather a copious amount of
-debugging traces for the operations done in those areas.
+Examples with useful log settings along with more information on how to properly
+configure logging for various situations can be found in the
+`logging knowledge base article <kbase/debuglogs.html>`__.
--
2.35.1
8:50 a.m.
New subject: [PATCH 28/29] docs: logging: Replace example by link to kbase/debuglogs.html
On Mon, Mar 28, 2022 at 02:10:43PM +0200, Peter Krempa wrote:
The 'debuglogs' knowledge base page has way more info and
examples on
how to set logging use it instead of the ad-hoc examples.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
7:10 a.m.
New subject: [PATCH 29/29] docs: Convert 'php' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/meson.build | 2 +-
docs/php.html.in | 28 ----------------------------
docs/php.rst | 23 +++++++++++++++++++++++
3 files changed, 24 insertions(+), 29 deletions(-)
delete mode 100644 docs/php.html.in
create mode 100644 docs/php.rst
diff --git a/docs/meson.build b/docs/meson.build
index f6e51353f0..c1def26655 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -27,7 +27,6 @@ docs_html_in_files = [
'formatnwfilter',
'index',
'internals',
- 'php',
'python',
'remote',
'storage',
@@ -100,6 +99,7 @@ docs_rst_files = [
'nss',
'pci-addresses',
'pci-hotplug',
+ 'php',
'platforms',
'programming-languages',
'securityprocess',
diff --git a/docs/php.html.in b/docs/php.html.in
deleted file mode 100644
index 9340c81eec..0000000000
--- a/docs/php.html.in
+++ /dev/null
@@ -1,28 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>PHP API bindings</h1>
-
-<h2>Presentation</h2>
- <p>The libvirt-php, originally called php-libvirt, is the PHP API bindings for
- the libvirt virtualization toolkit originally developed by Radek
Hladik.</p>
-
-<h2>Getting the source</h2>
-<p> The PHP bindings code source is now maintained in a <a
-href="https://git-scm.com/">git</a> repository available on
-<a href="https://gitlab.com/libvirt/libvirt-php">gitlab.com<...;:
-</p>
-<pre>
-git clone https://gitlab.com/libvirt/libvirt-php.git
-</pre>
-
-<p></p>
-<h2>Project pages</h2>
-<p>Since February 2011 the project has its own pages hosted at libvirt.org. For
more information on the project
- please refer to <a
href="https://libvirt.org/php">https://libvirt.org/php</a>;.
-
-</p>
-
- </body>
-</html>
diff --git a/docs/php.rst b/docs/php.rst
new file mode 100644
index 0000000000..36f7c44bed
--- /dev/null
+++ b/docs/php.rst
@@ -0,0 +1,23 @@
+================
+PHP API bindings
+================
+
+The libvirt-php, originally called php-libvirt, is the PHP API bindings for the
+libvirt virtualization toolkit originally developed by Radek Hladik.
+
+Getting the source
+------------------
+
+The PHP bindings code source is now maintained in a
+`git <https://git-scm.com/>`__ repository available on
+`gitlab.com <https://gitlab.com/libvirt/libvirt-php>`__:
+
+::
+
+ git clone https://gitlab.com/libvirt/libvirt-php.git
+
+Project pages
+-------------
+
+Since February 2011 the project has its own pages hosted at libvirt.org. For
+more information on the project please refer to https://libvirt.org/php.
--
2.35.1
8:51 a.m.
New subject: [PATCH 29/29] docs: Convert 'php' page to rST
Reviewed-by: Erik Skultety <eskultet(a)redhat.com>
2:23 a.m.
Can you please rebase? The series doesn't apply cleanly anymore.
Isn't this a part 3 actually? Based on [1]... :P
[1] https://listman.redhat.com/archives/libvir-list/2022-March/229208.html
Erik
2:56 a.m.
On Fri, Apr 01, 2022 at 09:23:54 +0200, Erik Skultety wrote:
Can you please rebase? The series doesn't apply cleanly anymore.
I've noted that patch 17 doesn't apply cleanly. I planned to drop it
(and solve the trivial conflict in docs/meson.build in patch 18).
Then I'll re-convert it in the next pass.
It doesn't make too much sense for me to try to chase and re-apply what
has changed to the converted docs.
Isn't this a part 3 actually? Based on [1]... :P
[1] https://listman.redhat.com/archives/libvir-list/2022-March/229208.html
It is, but that series is pushed for some time now. The problem was that
there was a docs change in one of the files converted in this series.
I can re-send with the conflict solved if you'd like me to.
960
days inactive
964
days old
63 comments
2 participants
participants (2)
-
Erik Skultety -
Peter Krempa