Reworded the local link so that it retains the sense. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index a0e8d69b87..a8d3e559c9 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -24,7 +24,6 @@ domain. The allowed values are driver specific, but include "xen", "kvm", and "lxc". The second attribute is ``id`` which is a unique integer identifier for the running guest machine. Inactive machines have no id value. -:anchor:`<a id="elementsMetadata"/>` General metadata ---------------- @@ -500,8 +499,8 @@ layout of sub-elements, with supported values of: Serial number ``uuid`` Universal Unique ID number. If this entry is provided alongside a - top-level `uuid <#elementsMetadata>`__ element, then the two values - must match. + top-level ``uuid`` element (see `General metadata`_), then the two + values must match. ``sku`` SKU number to identify a particular configuration. ``family`` -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 21 ++++++++++----------- docs/formatdomaincaps.rst | 6 +++--- 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 381d17370e..3936a31155 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -97,7 +97,6 @@ Operating system booting There are a number of different ways to boot virtual machines each with their own pros and cons. -:anchor:`<a id="elementsOSBIOS"/>` BIOS bootloader ~~~~~~~~~~~~~~~ @@ -332,11 +331,11 @@ and full virtualized guests. ... ``type`` - This element has the same semantics as described earlier in the `BIOS boot - section <#elementsOSBIOS>`__ + This element has the same semantics as described earlier in the + `BIOS bootloader`_ section. ``loader`` - This element has the same semantics as described earlier in the `BIOS boot - section <#elementsOSBIOS>`__ + This element has the same semantics as described earlier in the + `BIOS bootloader`_ section. ``kernel`` The contents of this element specify the fully-qualified path to the kernel image in the host OS. @@ -3197,7 +3196,7 @@ paravirtualized driver is specified via the ``disk`` element. attribute is an 8 character string which can be queried by guests on S390 via sclp or diag 308. Linux guests on S390 can use ``loadparm`` to select a boot entry. :since:`Since 3.5.0` The per-device ``boot`` elements cannot be used - together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__ + together with general boot elements in `BIOS bootloader`_ section. :since:`Since 0.8.8` ``encryption`` Starting with :since:`libvirt 3.9.0` the ``encryption`` element is preferred @@ -4240,8 +4239,8 @@ or: ``boot`` Specifies that the device is bootable. The ``order`` attribute determines the order in which devices will be tried during boot sequence. The per-device - ``boot`` elements cannot be used together with general boot elements in `BIOS - bootloader <#elementsOSBIOS>`__ section. :since:`Since 0.8.8` for PCI + ``boot`` elements cannot be used together with general boot elements in + `BIOS bootloader`_ section. :since:`Since 0.8.8` for PCI devices, :since:`Since 1.0.1` for USB devices. ``rom`` The ``rom`` element is used to change how a PCI device's ROM is presented to @@ -4384,8 +4383,8 @@ after 0.9.5 (KVM only)` : ``boot`` Specifies that the device is bootable. The ``order`` attribute determines the order in which devices will be tried during boot sequence. The per-device - ``boot`` elements cannot be used together with general boot elements in `BIOS - bootloader <#elementsOSBIOS>`__ section. ( :since:`Since 1.0.1` ) + ``boot`` elements cannot be used together with general boot elements in + `BIOS bootloader`_ section. ( :since:`Since 1.0.1` ) ``redirfilter`` The\ ``redirfilter``\ element is used for creating the filter rule to filter out certain devices from redirection. It uses sub-element ``<usbdev>`` to @@ -5415,7 +5414,7 @@ Specifying boot order For hypervisors which support this, you can set a specific NIC to be used for network boot. The ``order`` attribute determines the order in which devices will be tried during boot sequence. The per-device ``boot`` elements cannot be used -together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__ +together with general boot elements in `BIOS bootloader`_ section. :since:`Since 0.8.8` Interface ROM BIOS configuration diff --git a/docs/formatdomaincaps.rst b/docs/formatdomaincaps.rst index 55209e53c2..41a0b78959 100644 --- a/docs/formatdomaincaps.rst +++ b/docs/formatdomaincaps.rst @@ -71,11 +71,11 @@ The root element that emulator capability XML document starts with has name Describes the `virtualization type <formatdomain.html#element-and-attribute-overview>`__ (or so called domain type). ``machine`` - The domain's `machine type <formatdomain.html#elementsOSBIOS>`__. Since not + The domain's `machine type <formatdomain.html#bios-bootloader>`__. 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>`__. + The domain's `architecture <formatdomain.html#bios-bootloader>`__. CPU Allocation ~~~~~~~~~~~~~~ @@ -98,7 +98,7 @@ 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 +that, `os <formatdomain.html#bios-bootloader>`__ element exposes what values can be passed to its children. :: -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 1346c1ce01..f0bc9f6995 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -53,7 +53,7 @@ General metadata the virtual machine. The format must be RFC 4122 compliant, eg ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/creating a new machine, a random UUID is generated. It is also possible to provide the - UUID via a `sysinfo <#elementsSysinfo>`__ specification. :since:`Since 0.0.1, + UUID via a `SMBIOS System Information`_ specification. :since:`Since 0.0.1, sysinfo since 0.8.7` ``genid`` :since:`Since 4.4.0` , the ``genid`` element can be used to add a Virtual @@ -251,7 +251,7 @@ harddisk, cdrom, network) determining where to obtain/find the boot image. UUID, from the host's SMBIOS values; the `virConnectGetSysinfo <html/libvirt-libvirt-host.html#virConnectGetSysinfo>`__ call can be used to see what values are copied), or "sysinfo" (use the values - in the `sysinfo <#elementsSysinfo>`__ element). If not specified, the + in the `SMBIOS System Information`_ element). If not specified, the hypervisor default is used. :since:`Since 0.8.7` Up till here the BIOS/UEFI configuration knobs are generic enough to be @@ -407,7 +407,6 @@ If you want to enable user namespace, set the ``idmap`` element. The ``uid`` and <gid start='0' target='1000' count='10'/> </idmap> -:anchor:`<a id="elementsSysinfo"/>` SMBIOS System Information ------------------------- -- 2.35.3

Reworded documentation around local links. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 18 ++++++++---------- docs/formatdomaincaps.rst | 2 +- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 564ebbfd69..835dff3596 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -653,7 +653,6 @@ CPU Allocation same core need to be enabled as well. All non-hotpluggable CPUs present at boot need to be grouped after vCPU 0. :since:`Since 2.2.0 (QEMU only)` -:anchor:`<a id="elementsIOThreadsAllocation"/>` IOThreads Allocation -------------------- @@ -775,9 +774,8 @@ CPU Tuning of element ``vcpu`` is not specified, the IOThreads are pinned to all the physical CPUs by default. There are two required attributes, the attribute ``iothread`` specifies the IOThread ID and the attribute ``cpuset`` - specifying which physical CPUs to pin to. See the ``iothreadids`` - `description <#elementsIOThreadsAllocation>`__ for valid ``iothread`` values. - :since:`Since 1.2.9` + specifying which physical CPUs to pin to. See the `IOThreads Allocation`_ + section documenting valid values of ``iothread``. :since:`Since 1.2.9` ``shares`` The optional ``shares`` element specifies the proportional weighted share for the domain. If this is omitted, it defaults to the OS provided defaults. NB, @@ -851,8 +849,8 @@ CPU Tuning vCPUs/IOThreads this setting applies to, leaving them out sets the default. The element ``emulatorsched`` does not have that attribute. Valid ``vcpus`` values start at 0 through one less than the number of vCPU's defined for the - domain. Valid ``iothreads`` values are described in the ``iothreadids`` - `description <#elementsIOThreadsAllocation>`__. If no ``iothreadids`` are + domain. Valid ``iothreads`` values are described in the `IOThreads Allocation`_ + section. If no ``iothreadids`` are defined, then libvirt numbers IOThreads from 1 to the number of ``iothreads`` available for the domain. For real-time schedulers (``fifo``, ``rr``), priority must be specified as well (and is ignored for non-real-time ones). @@ -3131,8 +3129,8 @@ paravirtualized driver is specified via the ``disk`` element. intensive operation, but can save file space and/or time on slow media. :since:`Since 2.0.0` - The optional ``iothread`` attribute assigns the disk to an IOThread as - defined by the range for the domain - `iothreads <#elementsIOThreadsAllocation>`__ value. Multiple disks may be + defined by the range for the domain ``iothreads`` value. (See + `IOThreads Allocation`_). Multiple disks may be assigned to the same IOThread and are numbered from 1 to the domain iothreads value. Available for a disk device ``target`` configured to use "virtio" ``bus`` and "pci" or "ccw" ``address`` types. :since:`Since 1.2.8 @@ -3754,8 +3752,8 @@ An optional sub-element ``driver`` can specify the driver specific options: Supported for controller type ``scsi`` using model ``virtio-scsi`` for ``address`` types ``pci`` and ``ccw`` :since:`since 1.3.5 (QEMU 2.4)` . The optional ``iothread`` attribute assigns the controller to an IOThread as - defined by the range for the domain - `iothreads <#elementsIOThreadsAllocation>`__ value. Each SCSI ``disk`` + defined by the range for the domain ``iothreads`` (See `IOThreads Allocation`_). + Each SCSI ``disk`` assigned to use the specified ``controller`` will utilize the same IOThread. If a specific IOThread is desired for a specific SCSI ``disk``, then multiple controllers must be defined each having a specific ``iothread`` value. The diff --git a/docs/formatdomaincaps.rst b/docs/formatdomaincaps.rst index 41a0b78959..9ca7cdcc7c 100644 --- a/docs/formatdomaincaps.rst +++ b/docs/formatdomaincaps.rst @@ -232,7 +232,7 @@ I/O Threads ~~~~~~~~~~~ The ``iothread`` elements indicates whether or not `I/O -threads <formatdomain.html#elementsIOThreadsAllocation>`__ are supported. +threads <formatdomain.html#iothreads-allocation>`__ are supported. :: -- 2.35.3

Reworded documentation around local links. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 27e1e496e9..8e18151796 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -885,8 +885,7 @@ CPU Tuning but the ``unit`` attribute can be used to scale the value. ``unit`` (optional) If specified it is the unit such as KiB, MiB, GiB, or TiB (described in - the ``memory`` element for `Memory - Allocation <#elementsMemoryAllocation>`__) in which ``size`` is + the ``memory`` element for `Memory Allocation`_) in which ``size`` is specified, defaults to bytes. ``monitor`` :since:`Since 4.10.0` @@ -921,7 +920,6 @@ CPU Tuning The memory bandwidth to allocate from this node. The value by default is in percentage. -:anchor:`<a id="elementsMemoryAllocation"/>` Memory Allocation ----------------- @@ -1565,8 +1563,8 @@ maximum virtual CPUs number declared in ``vcpus``, to make the domain consistent across qemu and libvirt versions. ``memory`` specifies the node memory in kibibytes (i.e. blocks of 1024 bytes). :since:`Since 6.6.0` the ``cpus`` attribute is optional and if omitted a CPU-less NUMA node is created. -:since:`Since 1.2.11` one can use an additional -`unit <#elementsMemoryAllocation>`__ attribute to define units in which +:since:`Since 1.2.11` one can use an additional ``unit`` attribute +(See `Memory Allocation`_) to define units in which ``memory`` is specified. :since:`Since 1.2.7` all cells should have ``id`` attribute in case referring to some cell is necessary in the code, otherwise the cells are assigned ``id``\ s in the increasing order starting from 0. Mixing @@ -2034,7 +2032,7 @@ are: as 48 MiB of unavailable RAM might be too much for small guests (e.g. with 512 MiB of RAM). - See `Memory Allocation <#elementsMemoryAllocation>`__ for more details about + See `Memory Allocation`_ for more details about the ``unit`` attribute. :since:`Since 4.5.0` (QEMU only) ``ioapic`` @@ -7981,8 +7979,8 @@ Example: usage of the memory devices ``label`` For NVDIMM type devices one can use ``label`` and its subelement ``size`` to configure the size of namespaces label storage within the NVDIMM - module. The ``size`` element has usual meaning described - `here <#elementsMemoryAllocation>`__. ``label`` is mandatory for pSeries + module. The ``size`` element has usual meaning described in the + `Memory Allocation`_ section. ``label`` is mandatory for pSeries guests and optional for all other architectures. For QEMU domains the following restrictions apply: -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index fbebff8650..5cf31d9e06 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -1025,7 +1025,7 @@ influence how virtual memory pages are backed by host pages. amounts of locked memory could cause a denial-of-service attack on the host. Because of this, using this option is discouraged unless your workload demands it; even then, it's highly recommended to set a ``hard_limit`` (see - `memory tuning <#elementsMemoryTuning>`__) on memory allocation suitable for + `Memory Tuning`_) on memory allocation suitable for the specific environment at the same time to mitigate the risks described above. :since:`Since 1.0.6` ``source`` @@ -1046,7 +1046,6 @@ influence how virtual memory pages are backed by host pages. this is just an optimization and is not guaranteed to work in all cases (e.g. when hypervisor crashes). :since:`Since 4.4.0` (QEMU/KVM only) -:anchor:`<a id="elementsMemoryTuning"/>` Memory Tuning ------------- -- 2.35.3

Reworded documentation around the local link. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 6637ab409b..45f94e5fa2 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -1149,7 +1149,6 @@ NUMA Node Tuning element. This setting is not compatible with automatic placement. :since:`QEMU Since 1.2.7` -:anchor:`<a id="elementsBlockTuning"/>` Block I/O Tuning ---------------- @@ -2970,7 +2969,7 @@ paravirtualized driver is specified via the ``disk`` element. ``iotune`` The optional ``iotune`` element provides the ability to provide additional per-device I/O tuning, with values that can vary for each device (contrast - this to the `<blkiotune> <#elementsBlockTuning>`__ element, which applies + this to the ``blkiotune`` element (See `Block I/O Tuning`_), which applies globally to the domain). Currently, the only tuning available is Block I/O throttling for qemu. This element has optional sub-elements; any sub-element not specified or given with a value of 0 implies no limit. :since:`Since -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index e8431f972f..2851f28251 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -1630,7 +1630,6 @@ QEMU. If no ``distances`` are given to describe the SLIT data between different cells, it will default to a scheme using 10 for local and 20 for remote distances. -:anchor:`<a id="hmat"/>` ACPI Heterogeneous Memory Attribute Table ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 3 +-- docs/formatdomaincaps.rst | 2 +- docs/kbase/kvm-realtime.rst | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index acff214cc8..0247132d2b 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -1809,7 +1809,6 @@ advertisements to the guest OS. (NB: Only qemu driver support) the guest OS itself can choose to circumvent the unavailability of the sleep states (e.g. S4 by turning off completely). -:anchor:`<a id="elementsFeatures"/>` Hypervisor features ------------------- @@ -8047,7 +8046,7 @@ Example: ``eim`` The ``eim`` attribute (with possible values ``on`` and ``off``) can be used to configure Extended Interrupt Mode. A q35 domain with split I/O - APIC (as described in `hypervisor features <#elementsFeatures>`__), and + APIC (as described in `Hypervisor features`_), and both interrupt remapping and EIM turned on for the IOMMU, will be able to use more than 255 vCPUs. :since:`Since 3.4.0` (QEMU/KVM only) diff --git a/docs/formatdomaincaps.rst b/docs/formatdomaincaps.rst index d8fcf65450..7aead08d69 100644 --- a/docs/formatdomaincaps.rst +++ b/docs/formatdomaincaps.rst @@ -527,7 +527,7 @@ 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. +section <formatdomain.html#hypervisor-features>`__ in the domain XML documentation. GIC capabilities ^^^^^^^^^^^^^^^^ diff --git a/docs/kbase/kvm-realtime.rst b/docs/kbase/kvm-realtime.rst index f0a1bb7c95..890155560c 100644 --- a/docs/kbase/kvm-realtime.rst +++ b/docs/kbase/kvm-realtime.rst @@ -162,7 +162,7 @@ placement: </cpu> The performance monitoring unit virtualization needs to be disabled -via the `hypervisor features <../formatdomain.html#elementsFeatures>`_: +via the `hypervisor features <../formatdomain.html#hypervisor-features>`_: :: -- 2.35.3

Two paragraphs containing local links were reformulated and rewrapped. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatbackup.rst | 6 +++--- docs/formatcheckpoint.rst | 2 +- docs/formatdomain.rst | 21 +++++++++++---------- docs/formatsecret.rst | 10 +++++----- docs/formatsnapshot.rst | 6 +++--- docs/storage.rst | 6 +++--- 6 files changed, 26 insertions(+), 25 deletions(-) diff --git a/docs/formatbackup.rst b/docs/formatbackup.rst index c378ad9d9a..02847fd5d4 100644 --- a/docs/formatbackup.rst +++ b/docs/formatbackup.rst @@ -37,7 +37,7 @@ were supplied). The following child elements and attributes are supported: ``server`` Present only for a pull mode backup. Contains the same attributes as the - ```protocol`` element of a disk <formatdomain.html#elementsDisks>`__ attached + ```protocol`` element of a disk <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ attached via NBD in the domain (such as transport, socket, name, port, or tls), necessary to set up an NBD server that exposes the content of each disk at the time the backup is started. @@ -61,7 +61,7 @@ were supplied). The following child elements and attributes are supported: ``name`` A mandatory attribute which must match the ``<target dev='name'/>`` of - one of the `disk devices <formatdomain.html#elementsDisks>`__ specified + one of the `disk devices <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ specified for the domain at the time of the checkpoint. ``backup`` @@ -122,7 +122,7 @@ were supplied). The following child elements and attributes are supported: file is not deleted after the backup but the contents of the file don't make sense outside of the backup. The same applies for the block device which must be formatted appropriately. Similarly to the domain - ```disk`` <formatdomain.html#elementsDisks>`__ definition ``scratch`` + ```disk`` <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ definition ``scratch`` and ``target`` can contain ``seclabel`` and/or ``encryption`` subelements to configure the corresponding properties. diff --git a/docs/formatcheckpoint.rst b/docs/formatcheckpoint.rst index ff3f1e8c00..496de4e1ff 100644 --- a/docs/formatcheckpoint.rst +++ b/docs/formatcheckpoint.rst @@ -69,7 +69,7 @@ The top-level ``domaincheckpoint`` element may contain the following elements: ``name`` A mandatory attribute which must match either the ``<target dev='name'/>`` or an unambiguous ``<source file='name'/>`` of - one of the `disk devices <formatdomain.html#elementsDisks>`__ specified + one of the `disk devices <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ specified for the domain at the time of the checkpoint. ``checkpoint`` diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 4f85366c9d..d1134c523f 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -239,7 +239,7 @@ harddisk, cdrom, network) determining where to obtain/find the boot image. (the sorted list is vda, vdb, hda, hdc). Similar domain with hdc, vda, vdb, and hda disks will boot from hda (sorted disks are: hda, hdc, vda, vdb). It can be tricky to configure in the desired way, which is why per-device boot - elements (see `disks <#elementsDisks>`__, `network + elements (see `Hard drives, floppy disks, CDROMs`_, `network interfaces <#elementsNICS>`__, and `USB and PCI devices <#elementsHostDev>`__ sections below) were introduced and they are the preferred way providing full control over booting order. The ``boot`` element and per-device boot elements @@ -1186,12 +1186,13 @@ Block I/O Tuning ``device`` The domain may have multiple ``device`` elements that further tune the weights for each host block device in use by the domain. Note that multiple - `guest disks <#elementsDisks>`__ can share a single host block device, if - they are backed by files within the same host file system, which is why this - tuning parameter is at the global domain level rather than associated with - each guest disk device (contrast this to the `<iotune> <#elementsDisks>`__ - element which can apply to an individual ``<disk>``). Each ``device`` element - has two mandatory sub-elements, ``path`` describing the absolute path of the + disks (See `Hard drives, floppy disks, CDROMs`_) can share a single host + block device, if they are backed by files within the same host file system, + which is why this tuning parameter is at the global domain level rather than + associated with each guest disk device (contrast this to the <iotune> + element of a disk definition (See `Hard drives, floppy disks, CDROMs`_) + which can applies to an individual disk). Each ``device`` element has + two mandatory sub-elements, ``path`` describing the absolute path of the device, and ``weight`` giving the relative weight of that device, in the range [100, 1000]. After kernel 2.6.39, the value could be in the range [10, 1000]. :since:`Since 0.9.8` @@ -2331,7 +2332,6 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` ... </devices> -:anchor:`<a id="elementsDisks"/>` Hard drives, floppy disks, CDROMs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -4118,7 +4118,7 @@ or: "unfiltered", where the default is "filtered". The optional ``rawio`` ( :since:`since 1.2.9` ) attribute indicates whether the lun needs the rawio capability. Valid settings are "yes" or "no". See the rawio description - within the `disk <#elementsDisks>`__ section. If a disk lun in the domain + within the `Hard drives, floppy disks, CDROMs`_ section. If a disk lun in the domain already has the rawio capability, then this setting not required. ``scsi_host`` :since:`since 2.5.0` For SCSI devices, user is responsible to make sure @@ -4197,7 +4197,8 @@ or: :since:`Since 1.2.8` , the ``source`` element of a SCSI device may contain the ``protocol`` attribute. When the attribute is set to "iscsi", the host - device XML follows the network `disk <#elementsDisks>`__ device using the + device XML follows the network disk device + (See `Hard drives, floppy disks, CDROMs`_) using the same ``name`` attribute and optionally using the ``auth`` element to provide the authentication credentials to the iSCSI server. diff --git a/docs/formatsecret.rst b/docs/formatsecret.rst index 03c2836843..0327430078 100644 --- a/docs/formatsecret.rst +++ b/docs/formatsecret.rst @@ -65,7 +65,7 @@ using ``virsh secret-set-value``. 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#elementsDisks>`__ in order to provide the +`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: :: @@ -101,7 +101,7 @@ This secret is associated with a Ceph RBD (rados block device). The ``<usage type='ceph'>`` element must contain a single ``name`` element that 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#elementsDisks>`__ or a `storage pool +device <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ or a `storage pool (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: @@ -132,7 +132,7 @@ See `Setting secret values in virsh`_ on how to set the value of the secret using ``virsh secret-set-value``. The ceph secret can then be used by UUID or by the usage name via the ``<auth>`` -element in a domain's `<disk> <formatdomain.html#elementsDisks>`__ element as +element in a domain's `<disk> <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ element as follows: :: @@ -157,7 +157,7 @@ This secret is associated with an iSCSI target for CHAP authentication. The ``<usage type='iscsi'>`` element must contain a single ``target`` element that 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#elementsDisks>`__ or a `storage pool +device <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ or a `storage pool (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 @@ -207,7 +207,7 @@ See `Setting secret values in virsh`_ on how to set the value of the secret using ``virsh secret-set-value``. The iSCSI secret can then be used by UUID or by the usage name via the -``<auth>`` element in a domain's `<disk> <formatdomain.html#elementsDisks>`__ +``<auth>`` element in a domain's `<disk> <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ element as follows: :: diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst index dd742a3063..07aa03c0a7 100644 --- a/docs/formatsnapshot.rst +++ b/docs/formatsnapshot.rst @@ -115,11 +115,11 @@ The top-level ``domainsnapshot`` element may contain the following elements: This sub-element describes the snapshot properties of a specific disk. The attribute ``name`` is mandatory, and must match either the ``<target dev='name'/>`` (recommended) or an unambiguous ``<source file='name'/>`` - of one of the `disk devices <formatdomain.html#elementsDisks>`__ + of one of the `disk devices <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ specified for the domain at the time of the snapshot. The attribute ``snapshot`` is optional, and the possible values are the same as the ``snapshot`` attribute for `disk devices - <formatdomain.html#elementsDisks>`__ (``no``, ``internal``, or + <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ (``no``, ``internal``, or ``external``). Some hypervisors like ESX require that if specified, the snapshot mode must not override any snapshot mode attached to the corresponding domain disk, while others like qemu allow this field to @@ -140,7 +140,7 @@ The top-level ``domainsnapshot`` element may contain the following elements: overwrite the default ``file`` type. The ``type`` attribute along with the format of the ``source`` sub-element is identical to the ``source`` element used in domain disk definitions. See the `disk devices - <formatdomain.html#elementsDisks>`__ section documentation for further + <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ section documentation for further information. Libvirt currently supports the ``type`` element in the qemu driver and supported values are ``file``, ``block`` and ``network`` :since:`(since 1.2.2)`. diff --git a/docs/storage.rst b/docs/storage.rst index b860648628..9d5b193e31 100644 --- a/docs/storage.rst +++ b/docs/storage.rst @@ -557,7 +557,7 @@ Example RBD disk attachment RBD images can be attached to QEMU guests when QEMU is built with RBD support. Information about attaching a RBD image to a guest can be found at `format -domain <formatdomain.html#elementsDisks>`__ page. +domain <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ page. Valid RBD pool format types ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -618,7 +618,7 @@ Example Sheepdog disk attachment Sheepdog images can be attached to QEMU guests. Information about attaching a Sheepdog image to a guest can be found at the `format -domain <formatdomain.html#elementsDisks>`__ page. +domain <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ page. Valid Sheepdog pool format types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -698,7 +698,7 @@ Example Gluster disk attachment Files within a gluster volume can be attached to QEMU guests. Information about attaching a Gluster image to a guest can be found at the `format -domain <formatdomain.html#elementsDisks>`__ page. +domain <formatdomain.html#hard-drives-floppy-disks-cdroms>`__ page. Valid Gluster pool format types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 9d3960e7ad..91517b069f 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -3127,7 +3127,7 @@ paravirtualized driver is specified via the ``disk`` element. virtio-blk. ( :since:`Since 3.9.0` ) - The optional ``queue_size`` attribute specifies the size of each virt queue for virtio-blk. ( :since:`Since 7.8.0` ) - - For virtio disks, `Virtio-specific options <#elementsVirtio>`__ can also + - For virtio disks, `Virtio-related options`_ can also be set. ( :since:`Since 3.5.0` ) - The optional ``metadata_cache`` subelement controls aspects related to the format specific caching of storage image metadata. Note that this setting @@ -3431,7 +3431,7 @@ A directory on the host that can be accessed directly from the guest. "loop", with a format of "raw" or "nbd" with any format. QEMU supports a type of "path" or "handle", but no formats. Virtuozzo driver supports a type of "ploop" with a format of "ploop". - - For virtio-backed devices, `Virtio-specific options <#elementsVirtio>`__ + - For virtio-backed devices, `Virtio-related options`_ can also be set. ( :since:`Since 3.5.0` ) - For ``virtiofs``, the ``queue`` attribute can be used to specify the queue size (i.e. how many requests can the queue fit). ( :since:`Since 6.2.0` ) @@ -3565,7 +3565,6 @@ control where on the bus the device will be placed: will have access to it. ``<address type='unassigned'/>`` is an invalid address type for all other device types. :since:`Since 6.0.0` -:anchor:`<a id="elementsVirtio"/>` Virtio-related options ~~~~~~~~~~~~~~~~~~~~~~ @@ -3746,7 +3745,7 @@ An optional sub-element ``driver`` can specify the driver specific options: controllers must be defined each having a specific ``iothread`` value. The ``iothread`` value must be within the range 1 to the domain iothreads value. virtio options - For virtio controllers, `Virtio-specific options <#elementsVirtio>`__ can + For virtio controllers, `Virtio-related options`_ can also be set. ( :since:`Since 3.5.0` ) USB companion controllers have an optional sub-element ``<master>`` to specify @@ -5293,7 +5292,7 @@ following attributes are available for the ``"virtio"`` NIC driver: you know what you are doing. Proper RSS configuration depends from vcpu, tap, and vhost settings.** virtio options - For virtio interfaces, `Virtio-specific options <#elementsVirtio>`__ can also + For virtio interfaces, `Virtio-related options`_ can also be set. ( :since:`Since 3.5.0` ) Offloading options for the host and guest can be configured using the following @@ -5825,8 +5824,7 @@ change the grab key combination. <#elementsVirtioTransitional>`__ for more details. The subelement ``driver`` can be used to tune the virtio options of the device: -`Virtio-specific options <#elementsVirtio>`__ can also be set. ( :since:`Since -3.5.0` ) +`Virtio-related options`_ can also be set. ( :since:`Since 3.5.0` ) Hub devices ~~~~~~~~~~~ @@ -6247,8 +6245,7 @@ A video device. the default QEMU backend. "vhostuser" will use a separate vhost-user process backend (for ``virtio`` device). virtio options - `Virtio-specific options <#elementsVirtio>`__ can also be set ( - :since:`Since 3.5.0` ) + `Virtio-related options`_ can also be set (:since:`Since 3.5.0`) VGA configuration Control how the video devices exposed to the guest using the ``vgaconf`` attribute which takes the value "io", "on" or "off". At present, it's only @@ -7476,8 +7473,8 @@ Example: manually added device with static PCI slot 2 requested years) might be ignored. :since:`Since 1.1.1, requires QEMU 1.5` ``driver`` - For model ``virtio`` memballoon, `Virtio-specific - options <#elementsVirtio>`__ can also be set. ( :since:`Since 3.5.0` ) + For model ``virtio`` memballoon, `Virtio-related options`_ can also be set. + ( :since:`Since 3.5.0` ) Random number generator device ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -7551,8 +7548,7 @@ Example: usage of the RNG device: The subelement ``driver`` can be used to tune the device: virtio options - `Virtio-specific options <#elementsVirtio>`__ can also be set. ( - :since:`Since 3.5.0` ) + `Virtio-related options`_ can also be set. ( :since:`Since 3.5.0` ) :anchor:`<a id="elementsTpm"/>` @@ -8071,7 +8067,7 @@ attribute ``address`` of the ``cid`` element specifies the CID assigned to the guest. If the attribute ``auto`` is set to ``yes``, libvirt will assign a free CID automatically on domain startup. :since:`Since 4.4.0` The optional ``driver`` element allows to specify virtio options, see -`Virtio-specific options <#elementsVirtio>`__ for more details. :since:`Since 7.1.0` +`Virtio-related options`_ for more details. :since:`Since 7.1.0` :: -- 2.35.3

Local references were reworded. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 13d6e35ca8..403a03edfb 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -3234,7 +3234,7 @@ paravirtualized driver is specified via the ``disk`` element. ``address`` If present, the ``address`` element ties the disk to a given slot of a controller (the actual ``<controller>`` device can often be inferred by - libvirt, although it can be `explicitly specified <#elementsControllers>`__). + libvirt, although it can be be explicitly specified. See `Controllers`_). The ``type`` attribute is mandatory, and is typically "pci" or "drive". For a "pci" controller, additional attributes for ``bus``, ``slot``, and ``function`` must be present, as well as optional ``domain`` and @@ -3633,7 +3633,6 @@ posting <https://lists.gnu.org/archive/html/qemu-devel/2018-12/msg00923.html>`__ and the `virtio-1.0 spec <https://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html>`__. -:anchor:`<a id="elementsControllers"/>` Controllers ~~~~~~~~~~~ @@ -6311,8 +6310,7 @@ same values described above. :since:`Since 1.3.3` . ... Each character device element has an optional sub-element ``<address>`` which -can tie the device to a particular `controller <#elementsControllers>`__ or PCI -slot. +can tie the device to a particular controller (See `Controllers`_) or PCI slot. For character device with type ``unix`` or ``tcp`` the ``source`` has an optional element ``reconnect`` which configures reconnect timeout if the -- 2.35.3

The one local link addition prompted rewrapping of the whole paragraph. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 11 +++++------ docs/formatnetwork.rst | 4 ++-- docs/formatnetworkport.rst | 2 +- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 65197d6e3d..3618b1212a 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -239,11 +239,11 @@ harddisk, cdrom, network) determining where to obtain/find the boot image. (the sorted list is vda, vdb, hda, hdc). Similar domain with hdc, vda, vdb, and hda disks will boot from hda (sorted disks are: hda, hdc, vda, vdb). It can be tricky to configure in the desired way, which is why per-device boot - elements (see `Hard drives, floppy disks, CDROMs`_, `network - interfaces <#elementsNICS>`__, and `Host device assignment`_ - sections below) were introduced and they are the preferred way providing full - control over booting order. The ``boot`` element and per-device boot elements - are mutually exclusive. :since:`Since 0.1.3, per-device boot since 0.8.8` + elements (see `Hard drives, floppy disks, CDROMs`_, `Network interfaces`_, + and `Host device assignment`_ sections below) were introduced and they are + the preferred way providing full control over booting order. + The ``boot`` element and per-device boot elements are mutually exclusive. + :since:`Since 0.1.3, per-device boot since 0.8.8` ``smbios`` How to populate SMBIOS information visible in the guest. The ``mode`` attribute must be specified, and is either "emulate" (let the hypervisor @@ -4441,7 +4441,6 @@ Each mode supports an optional sub-element ``<address>`` (See `Device Addresses` which fine-tunes the correlation between the smartcard and a ccid bus controller. For now, qemu only supports at most one smartcard, with an address of bus=0 slot=0. -:anchor:`<a id="elementsNICS"/>` Network interfaces ~~~~~~~~~~~~~~~~~~ diff --git a/docs/formatnetwork.rst b/docs/formatnetwork.rst index d6550f6df9..d956178e56 100644 --- a/docs/formatnetwork.rst +++ b/docs/formatnetwork.rst @@ -61,7 +61,7 @@ The first elements provide basic metadata about the virtual network. The optional parameter ``trustGuestRxFilters`` can be used to set that attribute of the same name for each domain interface connected to this network ( :since:`since 1.2.10` ). See the `Network - interfaces <formatdomain.html#elementsNICS>`__ section of the domain XML + interfaces <formatdomain.html#network-interfaces>`__ section of the domain XML documentation for more details. Note that an explicit setting of this attribute in a portgroup or the individual domain interface will override the setting in the network. @@ -616,7 +616,7 @@ starting. portgroups also support the optional parameter ``trustGuestRxFilters`` which can be used to set that attribute of the same name for each domain interface using this portgroup ( :since:`since 1.2.10` ). See the `Network -interfaces <formatdomain.html#elementsNICS>`__ section of the domain XML +interfaces <formatdomain.html#network-interfaces>`__ section of the domain XML documentation for more details. Note that an explicit setting of this attribute in the portgroup overrides the network-wide setting, and an explicit setting in the individual domain interface will override the setting in the portgroup. diff --git a/docs/formatnetworkport.rst b/docs/formatnetworkport.rst index 6f1a24a52c..394c65c2b7 100644 --- a/docs/formatnetworkport.rst +++ b/docs/formatnetworkport.rst @@ -98,7 +98,7 @@ The following elements are common to one or more of the plug types listed later ``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>`__. + `interface documentation <formatdomain.html#network-interfaces>`__. Plugs ~~~~~ -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index bbf26edeba..d9d262d959 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -4513,8 +4513,7 @@ can be determined by examining the virtual network config with 'default' setup out of the box which does NAT'ing to the default route and has an IP range of ``192.168.122.0/255.255.255.0``. Each guest will have an associated tun device created with a name of vnetN, which can also be overridden -with the <target> element (see `overriding the target -element <#elementsNICSTargetOverride>`__). +with the <target> element (see `Overriding the target element`_). When the source of an interface is a network, a ``portgroup`` can be specified along with the name of the network; one network may have multiple portgroups @@ -4580,8 +4579,8 @@ static wired networking configs.** Provides a bridge from the VM directly to the LAN. This assumes there is a bridge device on the host which has one or more of the hosts physical NICs attached. The guest VM will have an associated tun device created with a name of -vnetN, which can also be overridden with the <target> element (see `overriding -the target element <#elementsNICSTargetOverride>`__). The tun device will be +vnetN, which can also be overridden with the <target> element (see +`Overriding the target element`_). The tun device will be attached to the bridge. The IP range / network configuration is whatever is used on the LAN. This provides the guest VM full incoming & outgoing net access just like a physical machine. @@ -5331,7 +5330,6 @@ bridge interfaces. This does not work in session mode. :since:`Since 1.2.9` For tap devices there is also ``sndbuf`` element which can adjust the size of send buffer in the host. :since:`Since 0.8.8` -:anchor:`<a id="elementsNICSTargetOverride"/>` Overriding the target element ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 5264d5fbf3..10503edab6 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5460,7 +5460,6 @@ outgoing traffic can be shaped independently. The ``bandwidth`` element and its child elements are described in the `QoS <formatnetwork.html#quality-of-service>`__ section of the Network XML. -:anchor:`<a id="elementVlanTag"/>` Setting VLAN tag (on supported network types only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 00d05adfb8..584cea36af 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5564,7 +5564,6 @@ specified as the value, the interface behaves as if it had the network cable disconnected. Default behavior if this element is unspecified is to have the link state ``up``. :since:`Since 0.9.5` -:anchor:`<a id="mtu"/>` MTU configuration ^^^^^^^^^^^^^^^^^ -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index f7d29e7403..4f09df9d48 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5236,8 +5236,8 @@ following attributes are available for the ``"virtio"`` NIC driver: ``queues`` The optional ``queues`` attribute controls the number of queues to be used for either `Multiqueue - virtio-net <https://www.linux-kvm.org/page/Multiqueue>`__ or - `vhost-user <#elementVhostuser>`__ network interfaces. Use of multiple packet + virtio-net <https://www.linux-kvm.org/page/Multiqueue>`__ or vhost-user (See + `vhost-user interface`_) network interfaces. Use of multiple packet processing queues requires the interface having the ``<model type='virtio'/>`` element. Each queue will potentially be handled by a different processor, resulting in much higher throughput. @@ -5679,7 +5679,6 @@ side of the network device. These are configured as subelements of the similarly named elements used to configure the guest side of the interface (described above). -:anchor:`<a id="elementVhostuser"/>` vhost-user interface ^^^^^^^^^^^^^^^^^^^^ -- 2.35.3

The surrounding paragraph around the only fixed use was rewrapped. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 73151c35f0..b3d254520e 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -4130,12 +4130,11 @@ or: 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 for an accelerated remote desktop backed by a mediated device (such as - NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `video - devices <#elementsVideo>`__. This attribute is limited to - ``model='vfio-pci'`` only. Supported values are either ``on`` or ``off`` - (default is 'off'). It is required to use a graphical framebuffer (See - `Graphical framebuffers`_) in order to use this attribute, - currently only supported with VNC, Spice and egl-headless graphics + NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `Video devices`_. + This attribute is limited to ``model='vfio-pci'`` only. Supported values + are either ``on`` or ``off`` (default is 'off'). It is required to use a + graphical framebuffer (See `Graphical framebuffers`_) in order to use this + attribute, currently only supported with VNC, Spice and egl-headless graphics devices. :since:`Since version 5.10.0` , there is an optional ``ramfb`` attribute for devices with ``model='vfio-pci'``. Supported values are either ``on`` or ``off`` (default is 'off'). When enabled, this attribute @@ -6125,7 +6124,6 @@ Only ``vnc``, ``spice`` and ``rdp`` supports ``<listen>`` element. :since:`Since the two APIs to pass a FD to QEMU in order to connect to this graphics device. Supported by graphics type ``vnc`` and ``spice``. -:anchor:`<a id="elementsVideo"/>` Video devices ~~~~~~~~~~~~~ -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 5f15c14093..3b9c18f6b4 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -274,8 +274,8 @@ them in production. ``bios`` This element has attribute ``useserial`` with possible values ``yes`` or ``no``. It enables or disables Serial Graphics Adapter which allows users to - see BIOS messages on a serial port. Therefore, one needs to have `serial - port <#elementCharSerial>`__ defined. :since:`Since 0.9.4` . :since:`Since + see BIOS messages on a serial port. Therefore, one needs to have `Serial port`_ + defined. :since:`Since 0.9.4` . :since:`Since 0.10.2 (QEMU only)` there is another attribute, ``rebootTimeout`` that controls whether and after how long the guest should start booting again in case the boot fails (according to BIOS). The value is in milliseconds with @@ -6330,7 +6330,6 @@ Parallel port ``target`` can have a ``port`` attribute, which specifies the port number. Ports are numbered starting from 0. There are usually 0, 1 or 2 parallel ports. -:anchor:`<a id="elementCharSerial"/>` Serial port ''''''''''' @@ -6437,7 +6436,7 @@ the ``console`` element might represent the same device as an existing ``serial`` element or a separate device. A ``target`` subelement is supported and works the same way as with the -``serial`` element (`see above <#elementCharSerial>`__ for details). Valid +``serial`` element (See `Serial port`_ for details). Valid values for the ``type`` attribute are: ``serial`` (described below); ``virtio`` (usable whenever VirtIO support is available); ``xen``, ``lxc`` and ``openvz`` (available when the corresponding hypervisor is in use). ``sclp`` and ``sclplm`` -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 1e279ad72e..d8004d4ad0 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -6624,7 +6624,6 @@ types have different ``target`` attributes. default will be used (client mode). :since:`Since 8.4.0` -:anchor:`<a id="elementsCharHostInterface"/>` Host interface ^^^^^^^^^^^^^^ @@ -7512,8 +7511,8 @@ Example: usage of the RNG device: ``egd`` This backend connects to a source using the EGD protocol. The source is - specified as a character device. Refer to `character device host - interface <#elementsCharHostInterface>`__ for more information. + specified as a character device. Refer to the `Host interface`_ for more + information. ``builtin`` This backend uses qemu builtin random generator, which uses -- 2.35.3

Local references were reworded to match. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index d63543db0b..a6e54246b8 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5920,7 +5920,7 @@ interaction with the admin. <audio id='1'> </graphics> - Where ``1`` is an id of the `audio device <#elementsAudio>`__. If no + Where ``1`` is an id of the audio device (See`Audio backends`_). If no ID is specified, then the default audio backend will be used. :since:`Since 7.2.0, qemu`. @@ -6077,7 +6077,7 @@ interaction with the admin. <audio id='1'> </graphics> - Where ``1`` is an id of the `audio device <#elementsAudio>`__. + Where ``1`` is an id of the audio device (See `Audio backends`_). Graphics device uses a ``<listen>`` to set up where the device should listen for clients. It has a mandatory attribute ``type`` which specifies the listen type. @@ -6971,11 +6971,10 @@ backend using the ``<audio>`` sub-element: </devices> ... -Where ``1`` is an id of the `audio device <#elementsAudio>`__. If no +Where ``1`` is an id of the audio device (See `Audio backends`_). If no ID is specified, then the default audio backend will be used. :since:`Since 6.7.0, bhyve; Since 7.2.0, qemu`. -:anchor:`<a id="elementsAudio"/>` Audio backends ~~~~~~~~~~~~~~ -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 1 - docs/kbase/memorydevices.rst | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index efe20e9654..2dec27b0b1 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -7769,7 +7769,6 @@ machines and the host. :since:`Since 1.2.10, QEMU and KVM only` the number of interrupt vectors. The ``ioeventd`` attribute enables/disables (values "on"/"off", respectively) ioeventfd. -:anchor:`<a id="elementsMemory"/>` Memory devices ~~~~~~~~~~~~~~ diff --git a/docs/kbase/memorydevices.rst b/docs/kbase/memorydevices.rst index 7f58a4247b..505b3b3828 100644 --- a/docs/kbase/memorydevices.rst +++ b/docs/kbase/memorydevices.rst @@ -79,7 +79,7 @@ Furthermore, DIMMs can have ``<source/>`` element which configures backend for devices. For NVDIMMs the element is mandatory and reflects where the content is saved. -See `memory devices documentation <../formatdomain.html#elementsMemory>`_. +See `memory devices documentation <../formatdomain.html#memory-devices>`_. ``virtio-mem`` model ==================== -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index cd3dcca1cb..8e0f254236 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -8024,7 +8024,6 @@ Example: mapping larger iova addresses in the guest. :since:`Since 6.5.0` (QEMU/KVM only) -:anchor:`<a id="vsock"/>` Vsock ~~~~~ -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index cffdab6eb7..97c23f6aa6 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -8142,7 +8142,6 @@ an output-only element ``labelskip`` will be present for active domains on disks where labeling was skipped due to the image being on a file system that lacks security labeling. -:anchor:`<a id="keywrap"/>` Key Wrap -------- -- 2.35.3

The role was used to pass through raw HTML to define custom anchor names. Since all of the document was now converted to use the anchors generated from headers we can remove it. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatdomain.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 4868d3c397..d27a295329 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -1,6 +1,4 @@ .. role:: since -.. role:: anchor(raw) - :format: html ================= Domain XML format -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/uri.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/uri.rst b/docs/uri.rst index 3ca3fb12c3..bfc9542260 100644 --- a/docs/uri.rst +++ b/docs/uri.rst @@ -291,7 +291,7 @@ Supported extra parameters: If set to a non-zero value, this disables client checks of the server's certificate. Note that to disable server checks of the client's certificate or IP address you must `change the libvirtd configuration - <#Remote_libvirtd_configuration>`__ + <remote.html#libvirtd-configuration-file>`__ **Example:** ``no_verify=1`` -- 2.35.3

Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/page.xsl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/page.xsl b/docs/page.xsl index 0a0b017482..1414d90b89 100644 --- a/docs/page.xsl +++ b/docs/page.xsl @@ -172,7 +172,7 @@ <div id="contact"> <h3>Contact</h3> <ul> - <li><a href="{$href_base}contact.html#mailng-lists">email</a></li> + <li><a href="{$href_base}contact.html#mailing-lists">email</a></li> <li><a href="{$href_base}contact.html#irc">irc</a></li> </ul> </div> -- 2.35.3

Linking to a list of files is not helpful. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- scripts/hvsupport.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/hvsupport.py b/scripts/hvsupport.py index 50ba25c78f..89fd0d1d94 100755 --- a/scripts/hvsupport.py +++ b/scripts/hvsupport.py @@ -426,7 +426,7 @@ print('''<?xml version="1.0" encoding="UTF-8"?> <ul id="toc"></ul> <p> -This page documents which <a href="html/">libvirt calls</a> work on +This page documents which libvirt calls work on which libvirt drivers / hypervisors, and which version the API appeared in. If a hypervisor driver later dropped support for the API, the version when it was removed is also mentioned (highlighted in -- 2.35.3

The link was not fixed when the page was moved into 'kbase/' Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/docs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs.rst b/docs/docs.rst index 0a698913be..9fd8b7c37e 100644 --- a/docs/docs.rst +++ b/docs/docs.rst @@ -26,7 +26,7 @@ Deployment / operation `Remote access <remote.html>`__ Enable remote access over TCP -`TLS certs <tlscerts.html>`__ +`TLS certs <kbase/tlscerts.html>`__ Generate and deploy x509 certificates for TLS `Authentication <auth.html>`__ -- 2.35.3

While the links work they'd trip up the link validator script which will be added later. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/api.rst | 2 +- docs/formatdomaincaps.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 08e5a0eed9..cdba642967 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -27,7 +27,7 @@ wise thing to do in most cases. See the `connection URI <uri.html>`__ page for a full descriptions of the values allowed. OnDevice the application obtains a -`virConnectPtr </html/libvirt-libvirt-host.html#virConnectPtr>`__ +`virConnectPtr <html/libvirt-libvirt-host.html#virConnectPtr>`__ connection to the hypervisor it can then use it to manage the hypervisor's available domains and related virtualization resources, such as storage and networking. All those are exposed as first class diff --git a/docs/formatdomaincaps.rst b/docs/formatdomaincaps.rst index 1ff45da6f0..933469b2a2 100644 --- a/docs/formatdomaincaps.rst +++ b/docs/formatdomaincaps.rst @@ -18,7 +18,7 @@ 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>`__ +`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. -- 2.35.3

The links were broken when the documentation was moved into the 'internals' subdirectory. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/kbase/internals/eventloop.rst | 2 +- docs/kbase/internals/migration.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/kbase/internals/eventloop.rst b/docs/kbase/internals/eventloop.rst index f25e97ab14..856cabc85f 100644 --- a/docs/kbase/internals/eventloop.rst +++ b/docs/kbase/internals/eventloop.rst @@ -47,7 +47,7 @@ To work with event loop from our code we have plenty of APIs. - ``virEventRemoveTimeout``: Unregisters a timer. For more information on these APIs continue reading -`here <../html/libvirt-libvirt-event.html>`__. +`here <../../html/libvirt-libvirt-event.html>`__. Worker pool ----------- diff --git a/docs/kbase/internals/migration.rst b/docs/kbase/internals/migration.rst index f7b4b5a10e..ad9d9426b2 100644 --- a/docs/kbase/internals/migration.rst +++ b/docs/kbase/internals/migration.rst @@ -7,7 +7,7 @@ Libvirt migration internals Migration is a multi-step operation with at least two distinct actors, the source and the destination libvirtd daemons, and a lot of failure points. This document describes the basic migration workflow in the -code level, as a way to complement `the base migration docs <../migration.html>`_ +code level, as a way to complement `the base migration docs <../../migration.html>`_ and help developers to get up to speed quicker with the code. In this document, unless stated otherwise, these conventions are followed: -- 2.35.3

Certain links were missing the '../' prefix to reach files in the parent directory from the time the page was introduced. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/kbase/kvm-realtime.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/kbase/kvm-realtime.rst b/docs/kbase/kvm-realtime.rst index 890155560c..87ab314bcb 100644 --- a/docs/kbase/kvm-realtime.rst +++ b/docs/kbase/kvm-realtime.rst @@ -150,7 +150,7 @@ siblings. This is achieved using the `CPU tuning config <../formatdomain.html#cp <vcpusched vcpus='0-4' scheduler='fifo' priority='1'/> </cputune> -The `guest CPU model <formatdomain.html#cpu-model-and-topology>`_ now needs to be +The `guest CPU model <../formatdomain.html#cpu-model-and-topology>`_ now needs to be configured to pass through the host model unchanged, with topology matching the placement: @@ -178,7 +178,7 @@ Memory configuration The host memory used for guest RAM needs to be allocated from huge pages on the second NUMA node, and all other memory allocation needs to be locked into RAM with memory page sharing disabled. -This is achieved by using the `memory backing config <formatdomain.html#memory-backing>`_: +This is achieved by using the `memory backing config <../formatdomain.html#memory-backing>`_: :: -- 2.35.3

Most of the links were broken by moving the article into kbase, but in this case we need to also fix the anchor names. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/kbase/tlscerts.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/kbase/tlscerts.rst b/docs/kbase/tlscerts.rst index 962253e853..e4aa5bb3c9 100644 --- a/docs/kbase/tlscerts.rst +++ b/docs/kbase/tlscerts.rst @@ -84,12 +84,12 @@ clients. There are two distinct checks involved: - The client should know that it is connecting to the right server. Checking done by client by matching the certificate that the server sends to the server's hostname. May be disabled by adding ``?no_verify=1`` to the `remote - URI <uri.html#Remote_URI_parameters>`__. + URI <../uri.html#tls-transport>`__. - The server should know that only permitted clients are connecting. This can be done based on client's IP address, or on client's IP address and client's certificate. Checking done by the server. May be enabled and disabled in the - `libvirtd.conf file <remote.html#libvirtd-configuration-file>`__. + `libvirtd.conf file <../remote.html#libvirtd-configuration-file>`__. For full certificate checking you will need to have certificates issued by a recognised `Certificate Authority @@ -99,7 +99,7 @@ CA, you can set up your own CA and tell your server(s) and clients to trust certificates issues by your own CA. Follow the instructions in the next section. Be aware that the `default configuration for -libvirtd <remote.html#libvirtd-configuration-file>`__ allows any client to +libvirtd <../remote.html#libvirtd-configuration-file>`__ allows any client to connect provided they have a valid certificate issued by the CA for their own IP address. You may want to change this to make it less (or more) permissive, depending on your needs. @@ -180,7 +180,7 @@ for validation may be discontinued entirely, so it is strongly recommended to include the SAN fields. In the example below, clients will be connecting to the server using a -`URI <uri.html#URI_remote>`__ of ``qemu://compute1.libvirt.org/system``, so the +`URI <../uri.html#remote-uris>`__ of ``qemu://compute1.libvirt.org/system``, so the CN must be "``compute1.libvirt.org``". Make a private key for the server: -- 2.35.3

When uri.html was converted to RST the 'URI remote' anchor was not fixed in remote.rst. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/remote.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/remote.rst b/docs/remote.rst index bcc394e083..ab11405d56 100644 --- a/docs/remote.rst +++ b/docs/remote.rst @@ -24,7 +24,7 @@ access the system-wide QEMU daemon, then to access the system-wide QEMU daemon on a remote machine called ``compute1.libvirt.org`` you would use ``qemu://compute1.libvirt.org/system``. -The `section on remote URIs <uri.html#URI_remote>`__ describes in more detail +The `section on remote URIs <uri.html#remote-uris>`__ describes in more detail these remote URIs. From an API point of view, apart from the change in URI, the API should behave @@ -82,7 +82,7 @@ Remote libvirt supports a range of transports: remote side. The choice of transport is determined by the `URI -scheme <uri.html#URI_remote>`__, with ``tls`` as the default if no explicit +scheme <uri.html#remote-uris>`__, with ``tls`` as the default if no explicit transport is requested. libvirtd configuration file -- 2.35.3

Link into the examples of the qemu driver. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/uri.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/uri.rst b/docs/uri.rst index bfc9542260..1d2c68f5b8 100644 --- a/docs/uri.rst +++ b/docs/uri.rst @@ -121,7 +121,7 @@ So to connect to the daemon, one of two different URIs is used: domain socket(s) that it listens on in the various different modes). KVM URIs are identical. You select between qemu, qemu accelerated and KVM guests -in the `guest XML as described here <format.html#KVM1>`__. +in the `guest XML as described here <drvqemu.html#example-domain-xml-config>`__. test:///... Test URIs ~~~~~~~~~~~~~~~~~~~~~ -- 2.35.3

The link was most likely broken when 'formatsecret' was converted to RST. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatstorageencryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/formatstorageencryption.rst b/docs/formatstorageencryption.rst index 11bea53cb8..2c19473d6b 100644 --- a/docs/formatstorageencryption.rst +++ b/docs/formatstorageencryption.rst @@ -107,7 +107,7 @@ to a qemu VM using the qemu VM driver. A single Examples -------- -Assuming a `luks volume type secret <formatsecret.html#VolumeUsageType>`__ is +Assuming a `luks volume type secret <formatsecret.html#usage-type-volume>`__ 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: -- 2.35.3

In many cases we move around or rename internal anchors which may break links leading to the content. docutils handle the case of links inside a document, but we are lacking the same form of checking between documents. Introduce a script which cross-checks all the anchors and links in HTML output files and prints problems and use it as a test case for the 'docs' directory. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 11 +++ scripts/check-html-references.py | 153 +++++++++++++++++++++++++++++++ scripts/meson.build | 1 + 3 files changed, 165 insertions(+) create mode 100755 scripts/check-html-references.py diff --git a/docs/meson.build b/docs/meson.build index d71f6006dd..cb70ef6084 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -350,3 +350,14 @@ run_target( ], depends: install_web_deps, ) + +test( + 'check-html-references', + python3_prog, + args: [ + check_html_references_prog.path(), + '--prefix', + meson.build_root() / 'docs' + ], + env: runutf8, +) diff --git a/scripts/check-html-references.py b/scripts/check-html-references.py new file mode 100755 index 0000000000..95a61a6bb4 --- /dev/null +++ b/scripts/check-html-references.py @@ -0,0 +1,153 @@ +#!/usr/bin/env python3 +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library. If not, see +# <http://www.gnu.org/licenses/>. +# +# Check that external references between documentation HTML files are not broken. + +import sys +import os +import argparse +import re +import xml.etree.ElementTree as ET + +ns = {'html': 'http://www.w3.org/1999/xhtml'} +externallinks = [] + + +def get_file_list(prefix): + filelist = [] + + for root, dir, files in os.walk(prefix): + prefixbase = os.path.dirname(prefix) + + if root.startswith(prefixbase): + relroot = root[len(prefixbase):] + else: + relroot = root + + for file in files: + if not re.search('\\.html$', file): + continue + + # the 404 page doesn't play well + if '404.html' in file: + continue + + fullfilename = os.path.join(root, file) + relfilename = os.path.join(relroot, file) + filelist.append((fullfilename, relfilename)) + + return filelist + + +# loads an XHTML and extracts all anchors, local and remote links for the one file +def process_file(filetuple): + filename, relfilename = filetuple + tree = ET.parse(filename) + root = tree.getroot() + + anchors = [relfilename] + targets = [] + + for elem in root.findall('.//html:a', ns): + target = elem.get('href') + an = elem.get('id') + + if an: + anchors.append(relfilename + '#' + an) + + if target: + if re.search('://', target): + externallinks.append(target) + elif target[0] != '#' and 'mailto:' not in target: + dirname = os.path.dirname(relfilename) + targetname = os.path.normpath(os.path.join(dirname, target)) + + targets.append((targetname, filename, target)) + + # older docutils generate "<div class='section'" + for elem in root.findall('.//html:div/[@class=\'section\']', ns): + an = elem.get('id') + + if an: + anchors.append(relfilename + '#' + an) + + # modern docutils generate a <section element + for elem in root.findall('.//html:section', ns): + an = elem.get('id') + + if an: + anchors.append(relfilename + '#' + an) + + return (anchors, targets) + + +def process_all(filelist): + anchors = [] + targets = [] + + for filetuple in filelist: + anchor, target = process_file(filetuple) + + targets = targets + target + anchors = anchors + anchor + + return (targets, anchors) + + +def check_targets(targets, anchors): + errors = [] + for target, targetfrom, targetorig in targets: + if target not in anchors: + errors.append((targetfrom, targetorig)) + + if errors: + errors.sort() + + print('broken link targets:') + + for file, target in errors: + print(file + " broken link: " + target) + + return True + + return False + + +parser = argparse.ArgumentParser(description='HTML reference checker') +parser.add_argument('--prefix', default='.', + help='build tree prefix') +parser.add_argument('--external', action="store_true", + help='print external references instead') + +args = parser.parse_args() + +files = get_file_list(args.prefix) + +targets, anchors = process_all(files) + +if args.external: + prev = None + externallinks.sort() + for ext in externallinks: + if ext != prev: + print(ext) + + prev = ext +else: + if check_targets(targets, anchors): + sys.exit(1) + + sys.exit(0) diff --git a/scripts/meson.build b/scripts/meson.build index 421e3d2acd..05b71184f1 100644 --- a/scripts/meson.build +++ b/scripts/meson.build @@ -6,6 +6,7 @@ scripts = [ 'check-driverimpls.py', 'check-drivername.py', 'check-file-access.py', + 'check-html-references.py', 'check-remote-protocol.py', 'check-symfile.py', 'check-symsorting.py', -- 2.35.3