docs: Add libvirt misc doc
A new dumping ground for libvirt'y things that can't easily be categorized or placed elsewhere. Change-Id: I6999b9d66e12e1df7970aff6ce63e5323de6be45 Signed-off-by: Stephen Finucane <stephenfin@redhat.com> Related-Bug: #1843542
This commit is contained in:
Stephen Finucane
parent
76549775fe
commit
9dfac32959
@ -384,18 +384,6 @@ See `the KVM documentation
|
||||
information on these limitations.
|
||||
|
||||
|
||||
Guest agent support
|
||||
-------------------
|
||||
|
||||
Use guest agents to enable optional access between compute nodes and guests
|
||||
through a socket, using the QMP protocol.
|
||||
|
||||
To enable this feature, you must set ``hw_qemu_guest_agent=yes`` as a metadata
|
||||
parameter on the image you wish to use to create the guest-agent-capable
|
||||
instances from. You can explicitly disable the feature by setting
|
||||
``hw_qemu_guest_agent=no`` in the image metadata.
|
||||
|
||||
|
||||
KVM performance tweaks
|
||||
----------------------
|
||||
|
||||
|
||||
@ -120,6 +120,7 @@ instance for these kind of workloads.
|
||||
managing-resource-providers
|
||||
resource-limits
|
||||
cpu-models
|
||||
libvirt-misc
|
||||
|
||||
|
||||
Additional guides
|
||||
|
||||
140
doc/source/admin/libvirt-misc.rst
Normal file
140
doc/source/admin/libvirt-misc.rst
Normal file
@ -0,0 +1,140 @@
|
||||
======================
|
||||
Other libvirt features
|
||||
======================
|
||||
|
||||
The libvirt driver supports a large number of additional features that don't
|
||||
warrant their own section. These are gathered here.
|
||||
|
||||
|
||||
Guest agent support
|
||||
-------------------
|
||||
|
||||
Guest agents enable optional access between compute nodes and guests through a
|
||||
socket, using the QMP protocol.
|
||||
|
||||
To enable this feature, you must set ``hw_qemu_guest_agent=yes`` as a metadata
|
||||
parameter on the image you wish to use to create the guest-agent-capable
|
||||
instances from. You can explicitly disable the feature by setting
|
||||
``hw_qemu_guest_agent=no`` in the image metadata.
|
||||
|
||||
|
||||
.. _extra-specs-watchdog-behavior:
|
||||
|
||||
Watchdog behavior
|
||||
-----------------
|
||||
|
||||
.. versionchanged:: 15.0.0 (Ocata)
|
||||
|
||||
Add support for the ``disabled`` option.
|
||||
|
||||
A virtual watchdog device can be used to keep an eye on the guest server and
|
||||
carry out a configured action if the server hangs. The watchdog uses the
|
||||
i6300esb device (emulating a PCI Intel 6300ESB). Watchdog behavior can be
|
||||
configured using the :nova:extra-spec:`hw:watchdog_action` flavor extra spec or
|
||||
equivalent image metadata property. If neither the extra spec not the image
|
||||
metadata property are specified, the watchdog is disabled.
|
||||
|
||||
For example, to enable the watchdog and configure it to forcefully reset the
|
||||
guest in the event of a hang, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack flavor set $FLAVOR --property hw:watchdog_action=reset
|
||||
|
||||
.. note::
|
||||
|
||||
Watchdog behavior set using the image metadata property will override
|
||||
behavior set using the flavor extra spec.
|
||||
|
||||
|
||||
.. _extra-specs-random-number-generator:
|
||||
|
||||
Random number generator
|
||||
-----------------------
|
||||
|
||||
.. versionchanged:: 21.0.0 (Ussuri)
|
||||
|
||||
Random number generators are now enabled by default for instances.
|
||||
|
||||
Operating systems require good sources of entropy for things like cryptographic
|
||||
software. If a random-number generator device has been added to the instance
|
||||
through its image properties, the device can be enabled and configured using
|
||||
the :nova:extra-spec:`hw_rng:allowed`, :nova:extra-spec:`hw_rng:rate_bytes` and
|
||||
:nova:extra-spec:`hw_rng:rate_period` flavor extra specs.
|
||||
|
||||
To configure for example a byte rate of 5 bytes per period and a period of 1000
|
||||
mSec (1 second), run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack flavor set $FLAVOR \
|
||||
--property hw_rng:rate_bytes=5 \
|
||||
--property hw_rng:rate_period=1000
|
||||
|
||||
Alternatively, to disable the random number generator, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack flavor set $FLAVOR --property hw_rng:allowed=false
|
||||
|
||||
The presence of separate byte rate and rate period configurables is
|
||||
intentional. As noted in the `QEMU docs`__, a smaller rate and larger period
|
||||
minimizes the opportunity for malicious guests to starve other guests of
|
||||
entropy but at the cost of responsiveness. Conversely, larger rates and smaller
|
||||
periods will increase the burst rate but at the potential cost of warping
|
||||
resource consumption in favour of a greedy guest.
|
||||
|
||||
.. __: https://wiki.qemu.org/Features/VirtIORNG#Effect_of_the_period_parameter
|
||||
|
||||
|
||||
.. _extra-specs-performance-monitoring-unit:
|
||||
|
||||
Performance Monitoring Unit (vPMU)
|
||||
----------------------------------
|
||||
|
||||
.. versionadded:: 20.0.0 (Train)
|
||||
|
||||
If nova is deployed with the libvirt virt driver and
|
||||
:oslo.config:option:`libvirt.virt_type` is set to ``qemu`` or ``kvm``, a
|
||||
virtual performance monitoring unit (vPMU) can be enabled or disabled for an
|
||||
instance using the :nova:extra-spec:`hw:pmu` flavor extra spec or ``hw_pmu``
|
||||
image metadata property.
|
||||
If the vPMU is not explicitly enabled or disabled via
|
||||
the flavor or image, its presence is left to QEMU to decide.
|
||||
|
||||
For example, to explicitly disable the vPMU, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack flavor set FLAVOR-NAME --property hw:pmu=false
|
||||
|
||||
The vPMU is used by tools like ``perf`` in the guest to provide more accurate
|
||||
information for profiling application and monitoring guest performance.
|
||||
For :doc:`real time </admin/real-time>` workloads, the emulation of a vPMU can
|
||||
introduce additional latency which would be undesirable. If the telemetry it
|
||||
provides is not required, the vPMU can be disabled. For most workloads the
|
||||
default of unset (enabled) will be correct.
|
||||
|
||||
|
||||
.. _extra-specs-hiding-hypervisor-signature:
|
||||
|
||||
Hiding hypervisor signature
|
||||
---------------------------
|
||||
|
||||
.. versionadded:: 18.0.0 (Rocky)
|
||||
|
||||
.. versionchanged:: 21.0.0 (Ussuri)
|
||||
|
||||
Prior to the Ussuri release, this was called ``hide_hypervisor_id``. An
|
||||
alias is provided to provide backwards compatibility.
|
||||
|
||||
Some hypervisors add a signature to their guests. While the presence of the
|
||||
signature can enable some paravirtualization features on the guest, it can also
|
||||
have the effect of preventing some drivers from loading. You can hide this
|
||||
signature by setting the :nova:extra-spec:`hw:hide_hypervisor_id` to true.
|
||||
|
||||
For example, to hide your signature from the guest OS, run:
|
||||
|
||||
.. code:: console
|
||||
|
||||
$ openstack flavor set $FLAVOR --property hw:hide_hypervisor_id=true
|
||||
@ -115,103 +115,6 @@ Hardware video RAM
|
||||
for more information on how this is used to set the ``videoRamSizeInKB`` attribute with
|
||||
the vmware driver.
|
||||
|
||||
.. _extra-specs-watchdog-behavior:
|
||||
|
||||
Watchdog behavior
|
||||
For the libvirt driver, you can enable and set the behavior of a virtual
|
||||
hardware watchdog device for each flavor. Watchdog devices keep an eye on the
|
||||
guest server, and carry out the configured action, if the server hangs. The
|
||||
watchdog uses the i6300esb device (emulating a PCI Intel 6300ESB). If
|
||||
``hw:watchdog_action`` is not specified, the watchdog is disabled.
|
||||
|
||||
To set the behavior, use:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack flavor set FLAVOR-NAME --property hw:watchdog_action=ACTION
|
||||
|
||||
Valid ACTION values are:
|
||||
|
||||
- ``disabled``: (default) The device is not attached.
|
||||
- ``reset``: Forcefully reset the guest.
|
||||
- ``poweroff``: Forcefully power off the guest.
|
||||
- ``pause``: Pause the guest.
|
||||
- ``none``: Only enable the watchdog; do nothing if the server hangs.
|
||||
|
||||
.. note::
|
||||
|
||||
Watchdog behavior set using a specific image's properties will override
|
||||
behavior set using flavors.
|
||||
|
||||
.. _extra-specs-random-number-generator:
|
||||
|
||||
Random-number generator
|
||||
If a random-number generator device has been added to the instance through
|
||||
its image properties, the device can be enabled and configured using:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack flavor set FLAVOR-NAME \
|
||||
--property hw_rng:allowed=True \
|
||||
--property hw_rng:rate_bytes=RATE-BYTES \
|
||||
--property hw_rng:rate_period=RATE-PERIOD
|
||||
|
||||
Where:
|
||||
|
||||
- RATE-BYTES: (integer) Allowed amount of bytes that the guest can read from
|
||||
the host's entropy per period.
|
||||
- RATE-PERIOD: (integer) Duration of the read period in milliseconds.
|
||||
|
||||
.. _extra-specs-performance-monitoring-unit:
|
||||
|
||||
Performance Monitoring Unit (vPMU)
|
||||
If nova is deployed with the libvirt virt driver and
|
||||
:oslo.config:option:`libvirt.virt_type` is set to ``qemu`` or ``kvm``, a
|
||||
vPMU can be enabled or disabled for an instance using the ``hw:pmu``
|
||||
extra_spec or the ``hw_pmu`` image property.
|
||||
The supported values are ``True`` or ``False``. If the vPMU is not
|
||||
explicitly enabled or disabled via the flavor or image, its presence is left
|
||||
to QEMU to decide.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ openstack flavor set FLAVOR-NAME --property hw:pmu=True|False
|
||||
|
||||
The vPMU is used by tools like ``perf`` in the guest to provide more accurate
|
||||
information for profiling application and monitoring guest performance.
|
||||
For realtime workloads, the emulation of a vPMU can introduce additional
|
||||
latency which may be undesirable. If the telemetry it provides is not
|
||||
required, such workloads should set ``hw:pmu=False``. For most workloads
|
||||
the default of unset or enabling the vPMU ``hw:pmu=True`` will be correct.
|
||||
|
||||
.. _extra-specs-hiding-hypervisor-signature:
|
||||
|
||||
Hiding hypervisor signature
|
||||
Some hypervisors add a signature to their guests. While the presence
|
||||
of the signature can enable some paravirtualization features on the
|
||||
guest, it can also have the effect of preventing some drivers from
|
||||
loading. Hiding the signature by setting this property to true may
|
||||
allow such drivers to load and work.
|
||||
|
||||
.. note::
|
||||
|
||||
As of the 18.0.0 Rocky release, this is only supported by the libvirt
|
||||
driver.
|
||||
|
||||
Prior to the 21.0.0 Ussuri release, this was called
|
||||
``hide_hypervisor_id``. An alias is provided to provide backwards
|
||||
compatibility.
|
||||
|
||||
.. code:: console
|
||||
|
||||
$ openstack flavor set FLAVOR-NAME \
|
||||
--property hw:hide_hypervisor_id=VALUE
|
||||
|
||||
Where:
|
||||
|
||||
- VALUE: (string) 'true' or 'false'. 'false' is equivalent to the
|
||||
property not existing.
|
||||
|
||||
.. _extra-specs-secure-boot:
|
||||
|
||||
Secure Boot
|
||||
|
||||
Loading…
Reference in New Issue
Block a user