External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 05:35:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Other fixes to :since: tags

Browse Source 
Make sure that they're entirely contained within a single line
and that punctuation is used in a way that doesn't make the
resulting HTML look weird.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This commit is contained in:
Andrea Bolognani 2024-02-19 11:33:45 +01:00
parent fd1dac6cd4
commit 96777db719
15 changed files with 367 additions and 354 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/drvbhyve.rst
View File

@ -268,7 +268,7 @@ these commands manually, most likely you might want to tweak them.
Using ZFS volumes
~~~~~~~~~~~~~~~~~
It's possible to use ZFS volumes as disk devices :since:`since 1.2.8` . An
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:
::
@ -307,7 +307,7 @@ not have spaces or they will be tokenized incorrectly.
Using UEFI bootrom, VNC, and USB tablet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:since:`Since 3.2.0` , in addition to
:since:`Since 3.2.0`, in addition to
`Using grub2-bhyve or Alternative Bootloaders`_, 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
@ -349,7 +349,7 @@ 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
:since:`Since 3.5.0`, it's possible to configure how the video device is
exposed to the guest using the ``vgaconf`` attribute:
::
@ -375,7 +375,7 @@ refer to the
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
: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):
@ -383,7 +383,7 @@ attribute):
<graphics type='vnc' autoport='yes'>
:since:`Since 6.8.0` , it's possible to set framebuffer resolution using the
:since:`Since 6.8.0`, it's possible to set framebuffer resolution using the
``resolution`` sub-element:
::
@ -394,7 +394,7 @@ attribute):
</model>
</video>
:since:`Since 6.8.0` , VNC server can be configured to use password based
:since:`Since 6.8.0`, VNC server can be configured to use password based
authentication:
::
@ -414,7 +414,7 @@ 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` ,
for *-CURRENT*. It's possible to use this in libvirt :since:`since 1.2.18`,
just place the following to domain XML:
::
@ -443,8 +443,8 @@ 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:
Intel e1000 network adapter emulation. It's supported in libvirt
:since:`since 3.1.0` and could be used as follows:
::
@ -460,7 +460,7 @@ 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 device emulation. It's supported in libvirt :since:`since 6.7.0`.
::
@ -484,7 +484,7 @@ 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` .
in libvirt :since:`since 6.9.0`.
::
@ -506,7 +506,7 @@ In the Linux guest, this could be mounted using:
Wiring guest memory
~~~~~~~~~~~~~~~~~~~
:since:`Since 4.4.0` , it's possible to specify that guest memory should be
:since:`Since 4.4.0`, it's possible to specify that guest memory should be
wired and cannot be swapped out as follows:
::
@ -522,7 +522,7 @@ wired and cannot be swapped out as follows:
CPU topology
~~~~~~~~~~~~
:since:`Since 4.5.0` , it's possible to specify guest CPU topology, if bhyve
: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:
@ -540,7 +540,7 @@ for *-CURRENT*. Example:
Ignoring unknown MSRs reads and writes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:since:`Since 5.1.0` , it's possible to make bhyve ignore accesses to
:since:`Since 5.1.0`, it's possible to make bhyve ignore accesses to
unimplemented Model Specific Registers (MSRs). Example:
::
@ -558,7 +558,7 @@ unimplemented Model Specific Registers (MSRs). Example:
Pass-through of arbitrary bhyve commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:since:`Since 5.1.0` , it's possible to pass additional command-line arguments
: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

19
docs/drvesx.rst
View File

@ -56,8 +56,9 @@ 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
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.
@ -75,7 +76,7 @@ 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` .
as well. The driver can handle folders :since:`since 0.9.7`.
::
@ -129,12 +130,12 @@ The driver understands the extra parameters shown below.
| | | set to 0, questions are |
| | | reported as errors. The |
| | | default value is 0. |
| | | :since:`Since 0.7.5` . |
| | | :since:`Since 0.7.5`. |
+-----------------+-----------------------------+-----------------------------+
| ``proxy`` | ``[type://]host[:port]`` | Allows to specify a proxy |
| | | for HTTP and HTTPS |
| | | communication. |
| | | :since:`Since 0.8.2` . The |
| | | :since:`Since 0.8.2`. The |
| | | optional ``type`` part may |
| | | be one of: ``http``, |
| | | ``socks``, ``socks4``, |
@ -272,8 +273,8 @@ 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`_ are supported.
- Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``.
:since:`Since 0.7.6` arbitrary `MAC addresses`_ are supported.
Datastore references
~~~~~~~~~~~~~~~~~~~~
@ -331,7 +332,7 @@ 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
: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.
@ -374,7 +375,7 @@ Here a domain XML snippet:
<controller type='scsi' index='0' model='lsilogic'/>
...
The controller element is supported :since:`since 0.8.2` . Prior to this
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.

2
docs/drvqemu.rst
View File

@ -562,7 +562,7 @@ The library provides two API: ``virDomainQemuMonitorCommand``, for sending an
arbitrary monitor command (in either HMP or QMP format) to a qemu guest (
:since:`Since 0.8.3` ), and ``virDomainQemuAttach``, for registering a qemu
domain that was manually started so that it can then be managed by libvirtd (
:since:`Since 0.9.4` , :removed:`removed as of 5.5.0` ).
:since:`Since 0.9.4`, :removed:`removed as of 5.5.0` ).
Additionally, the following XML additions allow fine-tuning of the command line
given to qemu when starting a domain ( :since:`Since 0.8.3` ). In order to use

2
docs/drvxen.rst
View File

@ -139,7 +139,7 @@ using libvirt Domain XML into xl, xm, or sxpr config format.
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
: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

8
docs/formatcaps.rst
View File

@ -148,11 +148,11 @@ The ``<guest/>`` element will typically wrap up the following elements:
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`
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`
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``

370
docs/formatdomain.rst
View File

File diff suppressed because it is too large Load Diff

55
docs/formatnetwork.rst
View File

@ -42,8 +42,8 @@ The first elements provide basic metadata about the virtual network.
The content of the ``name`` element provides a short name for the virtual
network. This name should consist only of alphanumeric characters and is
required to be unique within the scope of a single host. It is used to form
the filename for storing the persistent configuration file. :since:`Since
0.3.0`
the filename for storing the persistent configuration file.
:since:`Since 0.3.0`
``uuid``
The content of the ``uuid`` element provides a globally unique identifier for
the virtual network. The format must be RFC 4122 compliant, eg
@ -70,7 +70,7 @@ The first elements provide basic metadata about the virtual network.
setting in the network.
``title``
The optional element ``title`` provides space for a short description of the
network. The title should not contain any newlines. :since:`Since 9.7.0` .
network. The title should not contain any newlines. :since:`Since 9.7.0`.
``description``
The content of the ``description`` element provides a human readable
description of the network. This data is not used by libvirt in any
@ -141,7 +141,7 @@ to the physical LAN (if at all).
``mtu``
The ``size`` attribute of the ``<mtu>`` element specifies the Maximum
Transmission Unit (MTU) for the network. :since:`Since 3.1.0` . In the case
Transmission Unit (MTU) for the network. :since:`Since 3.1.0`. In the case
of a libvirt-managed network (one with forward mode of ``nat``, ``route``,
``open``, or no ``forward`` element (i.e. an isolated network), this will be
the MTU assigned to the bridge device when libvirt creates it, and thereafter
@ -170,7 +170,7 @@ to the physical LAN (if at all).
``forward``
Inclusion of the ``forward`` element indicates that the virtual network is to
be connected to the physical LAN. :since:`Since 0.3.0.` The ``mode``
be connected to the physical LAN. :since:`Since 0.3.0`. The ``mode``
attribute determines the method of forwarding. If there is no ``forward``
element, the network will be isolated from any other network (unless a guest
connected to that network is acting as a router, of course). The following
@ -287,8 +287,8 @@ to the physical LAN (if at all).
802.1Qbh-capable hardware switch), each physical interface can only be in
use by a single guest interface at a time; in modes other than 802.1Qbh,
multiple guest interfaces can share each physical interface (libvirt will
attempt to balance usage between all available interfaces). :since:`Since
0.9.4`
attempt to balance usage between all available interfaces).
:since:`Since 0.9.4`
``vepa``
This network uses a macvtap "direct" connection in "vepa" mode to connect
each guest to the network (this requires that the physical interfaces used
@ -319,8 +319,8 @@ to the physical LAN (if at all).
single-port PCI ethernet card driver design - only SR-IOV (Single Root I/O
Virtualization) virtual function (VF) devices can be assigned in this
manner; to assign a standard single-port PCI or PCIe ethernet card to a
guest, use the traditional ``<hostdev>`` device definition. :since:` Since
0.10.0`
guest, use the traditional ``<hostdev>`` device definition.
:since:`Since 0.10.0`
To force use of a particular device-specific VFIO driver when
assigning the devices to a guest, a <forward type='hostdev'>
@ -360,12 +360,12 @@ to the physical LAN (if at all).
</forward>
...
:since:`since 0.10.0` , ``<interface>`` also has an optional read-only
:since:`since 0.10.0`, ``<interface>`` also has an optional read-only
attribute - when examining the live configuration of a network, the attribute
``connections``, if present, specifies the number of guest interfaces
currently connected via this physical interface.
Additionally, :since:`since 0.9.10` , libvirt allows a shorthand for
Additionally, :since:`since 0.9.10`, libvirt allows a shorthand for
specifying all virtual interfaces associated with a single physical function,
by using the ``<pf>`` subelement to call out the corresponding physical
interface associated with multiple virtual interfaces:
@ -516,7 +516,7 @@ Setting VLAN tag (on supported network types only)
If (and only if) the network connection used by the guest supports VLAN tagging
transparent to the guest, an optional ``<vlan>`` element can specify one or more
VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` .
VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0`.
Network connections that support guest-transparent VLAN tagging include
``type='bridge'`` interfaces connected to an Open vSwitch bridge, SRIOV
@ -536,7 +536,7 @@ toplevel ``<vlan>`` element to differentiate trunking of a single tag from
normal tagging.
For network connections using Open vSwitch it is also possible to configure
'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0.` This is
'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0`. This is
done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement:
``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the
``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to
@ -562,7 +562,7 @@ Isolating ports from one another
<port isolated='yes'/>
</network>
:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to
:since:`Since 6.1.0`. The ``port`` element property ``isolated``, when set to
``yes`` (default setting is ``no``) is used to isolate the network traffic of
each guest on the network from all other guests connected to the network; it
does not have an effect on communication between the guests and the host, or
@ -640,7 +640,7 @@ Static Routes
Static route definitions are used to provide routing information to the
virtualization host for networks which are not directly reachable from the
virtualization host, but \*are\* reachable from a guest domain that is itself
reachable from the host :since:`since 1.0.6` .
reachable from the host :since:`since 1.0.6`.
As shown in `Network config with no gateway addresses`_ example, it is
possible to define a virtual network interface with no IPv4 or IPv6 addresses.
@ -729,17 +729,18 @@ of 'route' or 'nat'.
libvirt is running. :since:`Since 0.8.8`
``dns``
The dns element of a network contains configuration information for the
virtual network's DNS server :since:`Since 0.9.3` .
virtual network's DNS server :since:`Since 0.9.3`.
The dns element can have an optional ``enable`` attribute :since:`Since
2.2.0` . If ``enable`` is "no", then no DNS server will be setup by libvirt
The dns element can have an optional ``enable`` attribute
:since:`Since 2.2.0`.
If ``enable`` is "no", then no DNS server will be setup by libvirt
for this network (and any other configuration in ``<dns>`` will be ignored).
If ``enable`` is "yes" or unspecified (including the complete absence of any
``<dns>`` element) then a DNS server will be setup by libvirt to listen on
all IP addresses specified in the network's configuration.
The dns element can have an optional ``forwardPlainNames`` attribute
:since:`Since 1.1.2` . If ``forwardPlainNames`` is "no", then DNS resolution
:since:`Since 1.1.2`. If ``forwardPlainNames`` is "no", then DNS resolution
requests for names that are not qualified with a domain (i.e. names with no
"." character) will not be forwarded to the host's upstream DNS server - they
will only be resolved if they are known locally within the virtual network's
@ -761,7 +762,7 @@ of 'route' or 'nat'.
they can't be resolved locally). If an ``addr`` is specified by itself,
then all DNS requests to the network's DNS server will be forwarded to the
DNS server at that address with no exceptions. ``addr`` :since:`Since
1.1.3` , ``domain`` :since:`Since 2.2.0` .
1.1.3` , ``domain`` :since:`Since 2.2.0`.
``txt``
A ``dns`` element can have 0 or more ``txt`` elements. Each txt element
defines a DNS TXT record and has two attributes, both required: a name
@ -802,9 +803,9 @@ of 'route' or 'nat'.
network configured by the ``address`` and ``netmask``/``prefix`` attributes.
For some unusual network prefixes (not divisible by 8 for IPv4 or not
divisible by 4 for IPv6) libvirt may be unable to compute the PTR domain
automatically. The ``ip`` element is supported :since:`since 0.3.0` . IPv6,
automatically. The ``ip`` element is supported :since:`since 0.3.0`. IPv6,
multiple addresses on a single network, ``family``, and ``prefix`` are
supported :since:`since 0.8.7` . The ``ip`` element may contain the following
supported :since:`since 0.8.7`. The ``ip`` element may contain the following
elements:
``tftp``
@ -848,21 +849,21 @@ of 'route' or 'nat'.
which the boot image will be fetched. ``server`` defaults to the same
host that runs the DHCP server, as is the case when the ``tftp``
element is used. The BOOTP options currently have to be the same for
all address ranges and statically assigned addresses. :since:`Since
0.7.1`
all address ranges and statically assigned addresses.
:since:`Since 0.7.1`
Optionally, ``range`` and ``host`` elements can have ``lease`` child
element which specifies the lease time through it's attributes ``expiry``
and ``unit`` (which accepts ``seconds``, ``minutes`` and ``hours`` and
defaults to ``minutes`` if omitted). The minimal lease time is 2 minutes,
except when setting an infinite lease time (``expiry='0'``). :since:`Since
6.3.0`
except when setting an infinite lease time (``expiry='0'``).
:since:`Since 6.3.0`
Network namespaces
~~~~~~~~~~~~~~~~~~
A special XML namespace is available for passing options directly to the
underlying dnsmasq configuration file :since:`since 5.6.0` . Usage of XML
underlying dnsmasq configuration file :since:`since 5.6.0`. Usage of XML
namespaces comes with no support guarantees, so use at your own risk.
This example XML will pass the option strings ``foo=bar`` and

2
docs/formatnetworkport.rst
View File

@ -90,7 +90,7 @@ The following elements are common to one or more of the plug types listed later
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
: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

6
docs/formatnode.rst
View File

@ -115,7 +115,7 @@ Describes a device on the host's PCI bus. Sub-elements include:
capability element will also have an attribute named ``maxCount``
which is the maximum number of SRIOV VFs supported by this device,
which could be higher than the number of VFs that are currently
active :since:`since 1.3.0` ; in this case, even if there are
active :since:`since 1.3.0`; in this case, even if there are
currently no active VFs the virtual_functions capabililty will still
be shown.
``pci-bridge`` or ``cardbus-bridge``
@ -367,8 +367,8 @@ S390 architecture. Sub-elements include:
``vdpa``
^^^^^^^^
Describes a virtual datapath acceleration (vDPA) network device. :since:`Since
6.9.0` . Sub-elements include:
Describes a virtual datapath acceleration (vDPA) network device.
:since:`Since 6.9.0`. Sub-elements include:
``chardev``
The path to the character device that is used to access the device.

112
docs/formatnwfilter.rst
View File

@ -593,8 +593,8 @@ Note: Rules of this type should go into the ``root`` chain.
| protocolid | UINT16 (0x600-0xffff), | Layer 3 protocol ID |
| | STRING | |
+-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 |
| 0.8.5)` | | characters |
| comment | STRING | text with max. 256 |
| :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+
Valid Strings for ``protocolid`` are: arp, rarp, ipv4, ipv6
@ -710,20 +710,20 @@ chain.
| arpsrcipaddr | IP_ADDR | Source IP address in |
| | | ARP/RARP packet |
+-----------------------------+----------------+-----------------------------+
| arpsrcipmask :since:`(Since | IP_MASK | Source IP mask |
| 1.2.3)` | | |
| arpsrcipmask | IP_MASK | Source IP mask |
| :since:`(Since 1.2.3)` | | |
+-----------------------------+----------------+-----------------------------+
| arpdstipaddr | IP_ADDR | Destination IP address in |
| | | ARP/RARP packet |
+-----------------------------+----------------+-----------------------------+
| arpdstipmask :since:`(Since | IP_MASK | Destination IP mask |
| 1.2.3)` | | |
| arpdstipmask | IP_MASK | Destination IP mask |
| :since:`(Since 1.2.3)` | | |
+-----------------------------+----------------+-----------------------------+
| comment :since:`(Since | STRING | text with max. 256 |
| 0.8.5)` | | characters |
| comment | STRING | text with max. 256 |
| :since:`(Since 0.8.5)` | | characters |
+-----------------------------+----------------+-----------------------------+
| gratuitous :since:`(Since | BOOLEAN | boolean indicating whether |
| 0.9.2)` | | to check for gratuitous ARP |
| gratuitous | BOOLEAN | boolean indicating whether |
| :since:`(Since 0.9.2)` | | to check for gratuitous ARP |
| | | packet |
+-----------------------------+----------------+-----------------------------+
@ -783,8 +783,8 @@ Note: Rules of this type should either go into the ``root`` or ``ipv4`` chain.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 |
| 0.8.5)` | | characters |
| comment | STRING | text with max. 256 |
| :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+
Valid strings for ``protocol`` are: tcp, udp, udplite, esp, ah, icmp, igmp, sctp
@ -839,8 +839,8 @@ Note: Rules of this type should either go into the ``root`` or ``ipv6`` chain.
| | | ``protocol`` to be set to |
| | | ``icmpv6`` |
+--------------------------------+-----------+--------------------------------+
| typeend :since:`(Since | UINT8 | ICMPv6 type end of range; |
| 1.2.12)` | | requires ``protocol`` to be |
| typeend | UINT8 | ICMPv6 type end of range; |
| :since:`(Since 1.2.12)` | | requires ``protocol`` to be |
| | | set to ``icmpv6`` |
+--------------------------------+-----------+--------------------------------+
| code :since:`(Since 1.2.12)` | UINT8 | ICMPv6 code; requires |
@ -906,23 +906,23 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 |
| 0.8.5)` | | characters |
| comment | STRING | text with max. 256 |
| :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, |
| state | STRING | comma separated list of |
| :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID |
| | | or NONE |
+-------------------------+-------------------------+-------------------------+
| flags :since:`(Since | STRING | TCP-only: format of |
| 0.9.1)` | | mask/flags with mask |
| flags | STRING | TCP-only: format of |
| :since:`(Sinc 0.9.1)` | | mask/flags with mask |
| | | and flags each being a |
| | | comma separated list of |
| | | SYN,ACK,URG,PSH,FIN,RST |
| | | or NONE or ALL |
+-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of |
| ipset | STRING | The name of an IPSet |
| :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt |
+-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -981,16 +981,16 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 |
| 0.8.5)` | | characters |
| comment | STRING | text with max. 256 |
| :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, |
| state | STRING | comma separated list of |
| :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID |
| | | or NONE |
+-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of |
| ipset | STRING | The name of an IPSet |
| :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt |
+-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1045,16 +1045,16 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 |
| 0.8.5)` | | characters |
| comment | STRING | text with max. 256 |
| :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, |
| state | STRING | comma separated list of |
| :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID |
| | | or NONE |
+-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of |
| ipset | STRING | The name of an IPSet |
| :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt |
+-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1112,23 +1112,23 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 |
| 0.8.5)` | | characters |
| comment | STRING | text with max. 256 |
| :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, |
| state | STRING | comma separated list of |
| :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID |
| | | or NONE |
+-------------------------+-------------------------+-------------------------+
| flags :since:`(Since | STRING | TCP-only: format of |
| 0.9.1)` | | mask/flags with mask |
| flags | STRING | TCP-only: format of |
| :since:`(Since 0.9.1)` | | mask/flags with mask |
| | | and flags each being a |
| | | comma separated list of |
| | | SYN,ACK,URG,PSH,FIN,RST |
| | | or NONE or ALL |
+-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of |
| ipset | STRING | The name of an IPSet |
| :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt |
+-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1180,16 +1180,16 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 |
| 0.8.5)` | | characters |
| comment | STRING | text with max. 256 |
| :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, |
| state | STRING | comma separated list of |
| :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID |
| | | or NONE |
+-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of |
| ipset | STRING | The name of an IPSet |
| :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt |
+-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1237,16 +1237,16 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 |
| 0.8.5)` | | characters |
| comment | STRING | text with max. 256 |
| :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, |
| state | STRING | comma separated list of |
| :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID |
| | | or NONE |
+-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of |
| ipset | STRING | The name of an IPSet |
| :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt |
+-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1632,8 +1632,8 @@ connection, thus we want to allow it to let packets pass the firewall. The
outgoing TCP connection for the ftp data path. Afterwards, the state to compare
against is ``ESTABLISHED``, which then applies equally to the incoming and
outgoing direction. All this is related to the ftp data traffic originating from
TCP port 20 of the VM. This then leads to the following solution :since:`(since
0.8.5 (QEMU, KVM))` :
TCP port 20 of the VM. This then leads to the following solution
:since:`(since 0.8.5 (QEMU, KVM))` :
::

10
docs/formatsecret.rst
View File

@ -66,7 +66,7 @@ The volume type secret can be supplied either in volume XML during creation of a
`storage volume <formatstorage.html#storage-volume-xml>`__ in order to provide
the passphrase to encrypt the volume or in domain XML
`disk device <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ in order to provide the
passphrase to decrypt the volume, :since:`since 2.1.0` . An example follows:
passphrase to decrypt the volume, :since:`since 2.1.0`. An example follows:
::
@ -102,7 +102,7 @@ This secret is associated with a Ceph RBD (rados block device). The
specifies a usage name for the secret. The Ceph secret can then be used by UUID
or by this usage name via the ``<auth>`` element of a `disk
device <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ or a `storage pool
(rbd) <formatstorage.html>`__. :since:`Since 0.9.7` . The following is an
(rbd) <formatstorage.html>`__. :since:`Since 0.9.7`. The following is an
example of the steps to be taken. First create a ceph-secret.xml file:
::
@ -158,7 +158,7 @@ This secret is associated with an iSCSI target for CHAP authentication. The
specifies a usage name for the secret. The iSCSI secret can then be used by UUID
or by this usage name via the ``<auth>`` element of a `disk
device <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ or a `storage pool
(iscsi) <formatstorage.html>`__. :since:`Since 1.0.4` . The following is an
(iscsi) <formatstorage.html>`__. :since:`Since 1.0.4`. The following is an
example of the XML that may be used to generate a secret for iSCSI CHAP
authentication. Assume the following sample entry in an iSCSI authentication
file:
@ -231,7 +231,7 @@ Usage type "tls"
This secret may be used in order to provide the passphrase for the private key
used to provide TLS credentials. The ``<usage type='tls'>`` element must contain
a single ``name`` element that specifies a usage name for the secret.
:since:`Since 2.3.0` . The following is an example of the expected XML and
:since:`Since 2.3.0`. The following is an example of the expected XML and
processing to define the secret:
::
@ -269,7 +269,7 @@ passphrase for deriving a key from for encrypting the state of the vTPM. The
``<usage type='vtpm'>`` element must contain a single ``name`` element that
specifies a usage name for the secret. The vTPM secret can then be used by UUID
via the ``<encryption>`` element of a `tpm <formatdomain.html#tpm-device>`__
when using an emulator. :since:`Since 5.6.0` . The following is an example of
when using an emulator. :since:`Since 5.6.0`. The following is an example of
the steps to be taken. First create a vtpm-secret.xml file:
::

4
docs/formatsnapshot.rst
View File

@ -199,8 +199,8 @@ The top-level ``domainsnapshot`` element may contain the following elements:
uuid; reverting to a snapshot like this is risky if the current state of the
domain differs from the state that the domain was created in, and requires
the use of the ``VIR_DOMAIN_SNAPSHOT_REVERT_FORCE`` flag in
``virDomainRevertToSnapshot()``. Newer versions of libvirt ( :since:`since
0.9.5` ) store the entire inactive `domain configuration
``virDomainRevertToSnapshot()``. Newer versions of libvirt
(:since:`since 0.9.5`) store the entire inactive `domain configuration
<formatdomain.html>`__ at the time of the snapshot ( :since:`since 0.9.5` ).
The domain will have security-sensitive information omitted unless the flag
``VIR_DOMAIN_SNAPSHOT_XML_SECURE`` is provided on a read-write connection.

29
docs/formatstorage.rst
View File

@ -48,8 +48,8 @@ Storage pool general metadata
``allocation``
Providing the total storage allocation for the pool. This may be larger than
the sum of the allocation of all volumes due to metadata overhead. This value
is in bytes. This is not applicable when creating a pool. :since:`Since
0.4.1`
is in bytes. This is not applicable when creating a pool.
:since:`Since 0.4.1`
``capacity``
Providing the total storage capacity for the pool. Due to underlying device
constraints it may not be possible to use the full capacity for storage
@ -201,8 +201,8 @@ following child elements:
"scsi_host". To keep backwards compatibility, this attribute is optional
**only** for the "scsi_host" adapter, but is mandatory for the "fc_host"
adapter. :since:`Since 1.0.5` A "fc_host" capable scsi_hostN can be
determined by using ``virsh nodedev-list --cap fc_host``. :since:`Since
1.2.8`
determined by using ``virsh nodedev-list --cap fc_host``.
:since:`Since 1.2.8`
Note: Regardless of whether a "scsi_host" adapter type is defined using a
``name`` or a ``parentaddr``, it should refer to a real scsi_host adapter
@ -360,8 +360,8 @@ following child elements:
:since:`Since 0.8.4`
``product``
Provides an optional product name of the storage device. This contains a
single attribute ``name`` whose value is backend specific. :since:`Since
0.8.4`
single attribute ``name`` whose value is backend specific.
:since:`Since 0.8.4`
Storage pool target elements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -504,7 +504,7 @@ option in libvirt, and thus should never be used in production.
</pool>
...
:since:`Since 5.1.0.`
:since:`Since 5.1.0`.
``rbd:config_opts``
Provides an XML namespace mechanism to optionally utilize specifically named
@ -545,13 +545,14 @@ option in libvirt, and thus should never be used in production.
</rbd:config_opts>
</pool>
:since:`Since 5.1.0.`
:since:`Since 5.1.0`.
Storage volume XML
------------------
A storage volume will generally be either a file or a device node; :since:`since
1.2.0` , an optional output-only attribute ``type`` lists the actual type (file,
A storage volume will generally be either a file or a device node;
:since:`since 1.2.0`, an optional output-only attribute ``type`` lists
the actual type (file,
block, dir, network, netdir or ploop), which is also available from
``virStorageVolGetInfo()``. The storage volume XML format is available
:since:`since 0.4.1`
@ -609,12 +610,12 @@ Storage volume general metadata
``capacity``
Providing the logical capacity for the volume. This value is in bytes by
default, but a ``unit`` attribute can be specified with the same semantics as
for ``allocation`` This is compulsory when creating a volume. :since:`Since
0.4.1`
for ``allocation`` This is compulsory when creating a volume.
:since:`Since 0.4.1`
``physical``
This output only element provides the host physical size of the target
storage volume. The default output ``unit`` will be in bytes. :since:`Since
3.0.0`
storage volume. The default output ``unit`` will be in bytes.
:since:`Since 3.0.0`
``source``
Provides information about the underlying storage allocation of the volume.
This may not be available for some pool types. :since:`Since 0.4.1`

8
docs/formatstorageencryption.rst
View File

@ -46,7 +46,7 @@ it using the specified ``uuid``.
``qcow`` format
~~~~~~~~~~~~~~~
:since:`Since 4.5.0,` encryption formats ``default`` and ``qcow`` may no longer
: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
@ -59,7 +59,7 @@ 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 (except for the case of RBD layered encryption mentioned above).
:since:`Since 2.1.0` .
: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
@ -116,7 +116,7 @@ The ``luks-any`` format is currently supported only by the ``librbd`` engine,
and can only be applied to RBD network disks (RBD images). This format will try
to parse the disk as either LUKS or LUKS2, depending on the actual on-disk
format. A single ``<secret type='passphrase'...>`` element is expected (except
for the case of RBD layered encryption mentioned above) :since:`Since 9.3.0` .
for the case of RBD layered encryption mentioned above) :since:`Since 9.3.0`.
Examples
--------
@ -133,7 +133,7 @@ domain volume definition:
</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
algorithm for volume creation. :since:`Since 6.10.0`, the ``target`` format can
also support ``qcow2`` type with ``luks`` encryption.
::

64
docs/hooks.rst
View File

@ -34,7 +34,7 @@ The libvirt hook scripts are located in the directory
``/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
- :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,
@ -60,7 +60,7 @@ At present, there are five hook scripts that can be called:
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
: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.
@ -179,7 +179,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
- 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
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:
@ -187,7 +187,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/qemu guest_name prepare begin -
The second location, available :since:`Since 0.8.0` , occurs after libvirt
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:
@ -195,7 +195,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/qemu guest_name start begin -
The third location, :since:`0.9.13` , occurs after the QEMU process has
The third location, :since:`0.9.13`, occurs after the QEMU process has
successfully started up:
::
@ -203,7 +203,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/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
locations, to match the startup. First, :since:`since 0.8.0`, the hook is
called before libvirt restores any labels:
::
@ -211,13 +211,13 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/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:
: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
- :since:`Since 0.9.11`, the qemu hook script is also called at the beginning
of incoming migration. It is called as:
::
@ -231,7 +231,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
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
- :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:
@ -246,7 +246,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
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
- :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
@ -255,7 +255,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
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
- :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:
@ -263,7 +263,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/qemu guest_name reconnect begin -
- :since:`Since 0.9.13` , the qemu hook script is also called when the QEMU
- :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:
@ -276,7 +276,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
- 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
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:
@ -284,7 +284,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/lxc guest_name prepare begin -
The second location, available :since:`Since 0.8.0` , occurs after libvirt
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:
@ -292,7 +292,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/lxc guest_name start begin -
The third location, :since:`0.9.13` , occurs after the LXC process has
The third location, :since:`0.9.13`, occurs after the LXC process has
successfully started up:
::
@ -300,7 +300,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/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
locations, to match the startup. First, :since:`since 0.8.0`, the hook is
called before libvirt restores any labels:
::
@ -308,13 +308,13 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/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:
: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
- :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:
@ -327,7 +327,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
- 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
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:
@ -335,7 +335,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/libxl guest_name prepare begin -
The second location, available :since:`Since 2.1.0` , occurs after libvirt
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:
@ -343,7 +343,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/libxl guest_name start begin -
The third location, :since:`2.1.0` , occurs after the domain has
The third location, :since:`2.1.0`, occurs after the domain has
successfully started up:
::
@ -351,7 +351,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/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
in two locations, to match the startup. First, :since:`since 2.1.0`, the
hook is called before libvirt restores any labels:
::
@ -359,13 +359,13 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/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:
: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
- :since:`Since 2.1.0`, the libxl hook script is also called at the beginning
of incoming migration. It is called as:
::
@ -379,7 +379,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
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
- :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
@ -388,7 +388,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
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
- :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:
@ -401,7 +401,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
- Before an bhyve guest is started, the bhyve hook script is called in three
locations; if any location fails, the guest is not started. The first
location, :since:`since 6.1.0` , is before libvirt performs any resource
location, :since:`since 6.1.0`, is before libvirt performs any resource
labeling, and the hook can allocate resources not managed by libvirt. This is
called as:
@ -409,7 +409,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/bhyve guest_name prepare begin -
The second location, available :since:`Since 6.1.0` , occurs after libvirt
The second location, available :since:`Since 6.1.0`, occurs after libvirt
has finished labeling all resources, but has not yet started the guest,
called as:
@ -417,7 +417,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/bhyve guest_name start begin -
The third location, :since:`6.1.0` , occurs after the bhyve process has
The third location, :since:`6.1.0`, occurs after the bhyve process has
successfully started up:
::
@ -425,7 +425,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/bhyve guest_name started begin -
- When an bhyve guest is stopped, the bhyve hook script is called in two
locations, to match the startup. First, :since:`since 6.1.0` , the hook is
locations, to match the startup. First, :since:`since 6.1.0`, the hook is
called before libvirt restores any labels:
::
@ -433,7 +433,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/bhyve guest_name stopped end -
Then, after libvirt has released all resources, the hook is called again,
:since:`since 6.1.0` , to allow any additional resource cleanup:
:since:`since 6.1.0`, to allow any additional resource cleanup:
::
@ -442,7 +442,7 @@ operation. There is no specific operation to indicate a "restart" is occurring.
/etc/libvirt/hooks/network
^^^^^^^^^^^^^^^^^^^^^^^^^^
- :since:`Since 1.2.2` , before a network is started, this script is called
- :since:`Since 1.2.2`, before a network is started, this script is called
as:
::