Commit Graph

4075 Commits

Author SHA1 Message Date
Tim Wiederhake
c807f65de6 docs: coding-style: Remove "no_memory" as acceptable goto target
There are no instances of that label left.

Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-01-17 10:59:19 +01:00
Tim Wiederhake
15ca9bf2bc docs: coding-style: Rewrite section on shortening comparisons
The code style showed `bool hasFoos; if (hasFoos == true)` as a
good example in one place, only to warn against comparisons with
`true` a couple of paragraphs further down.

Merge this advice on comparing with `true` into the "Conditional
expressions" section and split the example up for readability.

Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-01-17 10:58:59 +01:00
Daniel P. Berrangé
4bb150ed3a docs: use virYesNo definition in more schemas
A few places are still using an expend yes/no choice instead of the
common virYesNo definition.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2022-01-14 18:56:37 +00:00
Daniel P. Berrangé
08e3d9ed24 docs: split example for <os> schema
The docs illustration for the <os> schema contains a mixture of
incompatible configuration options. This is rather confusing and
misleading to users. Splitting the illustration into four separate
examples clarifies the situation.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2022-01-14 18:56:23 +00:00
Ivan Teterevkov
19407e8d7d meson: Detect rst2html5 and rst2man only when needed
Detect these commands in docs/meson.build, i.e. only when
users enable documentation.

Signed-off-by: Ivan Teterevkov <ivan.teterevkov@nutanix.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
2022-01-14 18:17:56 +01:00
Andrea Bolognani
55a248d354 virt-ssh-helper: Move manual page to section 8
While sections are somewhat loosely defined and thus the choice
is not quite a clear-cut one, section 8 might be a slightly
better fit in this case.

Suggested-by: Olaf Hering <olaf@aepfle.de>
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-01-13 16:07:56 +01:00
Stefan Berger
7c17572798 docs: tpm: Clarify omission or removal of active_pcr_banks node
Add a sentence to the active_pcr_banks node documentation that clarifies
that when the active_pcr_banks node is removed from the XML or when it
is omitted that the set of active PCR banks is not changed anymore.

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2039246
Signed-off-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
2022-01-13 10:44:15 +01:00
Boris Fiuczynski
654c72ee94 docs: minor fix in launchSecurity
Correcting XML element.

Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2022-01-13 10:22:24 +01:00
Andrea Bolognani
82d514084a virt-ssh-helper: Add manual page
We don't usually provide manual pages for internal tools,
but in the case of virt-ssh-helper the command is installed
inside the default $PATH and so it's likely that the user
will stumble upon it by using the shell's completion feature
when invoking another virt-* command, which makes it a good
idea to provide at least a minimal manual page.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2022-01-07 17:02:17 +01:00
Jim Fehlig
3fc65ae9e2 tools: Add domsetlaunchsecstate virsh command
After attesting a domain with the help of domlaunchsecinfo,
domsetlaunchsecstate can be used to set a secret in the guest
domain's memory prior to running the vcpus.

Signed-off-by: Jim Fehlig <jfehlig@suse.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-01-04 10:56:00 -07:00
Michal Privoznik
f3b422d9cc docs: Clarify 'burst' units for QoS
The burst attribute for bandwidth specifies how much bytes can be
transmitted in a single burst. Therefore, the unit is in
multiples of 1024 (thus kibibytes) not SI-like 1000. It has
always been like that.

The 'tc' output is still confusing though, for instance:

  # tc class add dev $DEV parent 1: classid 1:1 htb rate 1000kbps burst 2097152
  # tc class show dev vnet2
  class htb 1:1 root rate 8Mbit ceil 8Mbit burst 2Mb cburst 1600b

Please note that 2097152 = 2*1024*1024. Even the man page is
confusing. From tc(8):

  kb or k        Kilobytes
  mb or m        Megabytes

But I guess this is because 'tc' predates IEC standardisation of
binary multiples and thus can't change without breaking scripts
parsing its output.

And while at it, adjust _virNetDevBandwidthRate struct member
description, to make it obvious which members use SI/IEC units.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
2022-01-04 16:40:10 +01:00
Andrea Bolognani
8c2d9794dc docs: Move font definitions with other CSS files
We have a subdirectory specifically for CSS files now, so it makes
sense to have the stylesheet that defines fonts to be there too.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-01-04 15:47:28 +01:00
Andrea Bolognani
7163515aa9 docs: Move all CSS files to a subdirectory
This unclutters the top-level docs directory.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-01-04 15:47:27 +01:00
Andrea Bolognani
630f376bc0 docs: Move all images to a subdirectory
This unclutters the top-level docs directory.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ani Sinha <ani@anisinha.ca>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-01-04 15:47:25 +01:00
Andrea Bolognani
19cc4e0eb8 docs: Drop structures.svg
It was introduced in ff4ede0055 but it doesn't seem to have
ever actually been used anywhere.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ani Sinha <ani@anisinha.ca>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-01-04 15:47:21 +01:00
Andrea Bolognani
81971f1de7 docs: Fix indentation in shell snippet
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
2021-12-24 10:47:44 +01:00
Peter Krempa
66566e84b8 storage: Introduce 'extended_l2' feature for storage volume
QCOW2 images now support 'extended_l2' which splits the default clusters
into 32 subcluster allocation units. This allows the allocation units to
be smaller without increasing the size of L2 table too much and thus also
the cache requirements for holding the full L2 table in memory.

Unfortunately it's incompatible with qemu versions older than 5.2 thus
can't be used as default.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-21 13:23:09 +01:00
Peter Krempa
14584c665e docs: formatstorage: Convert to RST
Apart from the bulk conversion itself, the section names 'general
metadata' and 'target elements' were duplicated between the storage pool
and storage volume sections. To prevent heading name clashes they were
renamed appropriately.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-21 13:23:09 +01:00
Andrea Bolognani
e1bfb2ad67 docs: Remove dependency on external resources
The internals/eventloop document uses two images for
illustrative purposes, but unlike other graphics included
in the documentation these are not part of libvirt.git but
rather were added to libvirt-media.git with

  commit fae5622074cf5e18d190496f8a43260c614599b2
  Author: Michal Privoznik <mprivozn@redhat.com>
  Date:   Mon Jun 6 17:27:50 2016 +0200

    Add two event loop images

    These images are going to be used in our documentation of the
    event loop.

    Signed-off-by: Michal Privoznik <mprivozn@redhat.com>

  fae5622074

and are requested directly from there. Specifically, the
URLs point to the libvirt.org mirror of libvirt-media.git
instead of the primary repository hosted on GitLab.

Import the images into libvirt.git so that the website
doesn't rely on external resources and can, if desired, be
browsed entirely offline from installed packages.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2021-12-21 10:19:27 +01:00
Michal Privoznik
06f405c627 qemu: Explicitly forbid live changing nodeset for strict numatune
Let's imagine a guest that's configured with strict numatune:

  <numatune>
    <memory mode='strict' nodeset='0'/>
  </numatune>

For guests with NUMA:
Depending on machine type used (see commit v6.4.0-rc1~75) we
generate either:

  1) -object '{"qom-type":"memory-backend-ram","id":"ram-node0",\
               "size":20971520,"host-nodes":[0],"policy":"preferred"}' \
     -numa node,nodeid=0,cpus=0,memdev=ram-node0

or

  2) -numa node,nodeid=0,cpus=0,mem=20480

Later, when QEMU boots up and cpuset CGroup controller is
available we further restrict QEMU there too. But there's a
behaviour difference hidden: while in case 1) QEMU is restricted
from beginning, in case 2) it is not and thus it may happen that
it will allocate memory from different NUMA node and even though
CGroup will try to migrate it, it may fail to do so (e.g. because
memory is locked). Therefore, one can argue that case 2) is
broken. NB, case 2) is exactly what mode 'restrictive' is for.
However, in case 1) we are unable to update QEMU with new
host-nodes, simply because it's lacking a command to do so.

For guests without NUMA:
It's very close to case 2) from above. We have commit
v7.10.0-rc1~163 that prevents us from outputting host-nodes when
generating memory-backend-* for system memory, but that simply
allows QEMU to allocate memory anywhere and then relies on
CGroups to move it to desired location.

Due to all of this, there is no reliable way to change nodeset
for mode 'strict'. Let's forbid it.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2021-12-17 13:21:48 +01:00
Michal Privoznik
a19b93d4e0 qemu: Allow VIR_DOMAIN_NUMATUNE_MEM_RESTRICTIVE in qemuDomainSetNumaParamsLive()
The whole idea of VIR_DOMAIN_NUMATUNE_MEM_RESTRICTIVE is that the
memory location is restricted only via CGroups and thus can be
changed on the fly (which is exactly what
qemuDomainSetNumaParamsLive() does. Allow this mode there then.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2021-12-17 13:18:54 +01:00
Michal Privoznik
d05a89b703 manpages: Document 'restrictive' mode for numatune
While we document possibility of passing an integer from
virDomainNumatuneMemMode enum, we list string variants to only
the first three enum members. The fourth (and so far the last)
member is called 'restrictive' and thus should be documented.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2021-12-17 12:50:05 +01:00
Daniel P. Berrangé
cd4e917760 conf: add support for setting SEV kernel hashes
Normally the SEV measurement only covers the firmware
loader contents. When doing a direct kernel boot, however,
with new enough OVMF it is possible to ask for the
measurement to cover the kernel, ramdisk and command line.

It can't be done automatically as that would break existing
guests using direct kernel boot with old firmware, so there
is a new XML setting allowing this behaviour to be toggled.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2021-12-16 18:02:58 +00:00
Tim Wiederhake
0519787f88 docs: domain: Clarify on the dangers of migrating with hyperv-passthrough enabled
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2021-12-15 11:53:08 +01:00
Tim Wiederhake
fdec0cbf43 Fix some typos
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2021-12-15 11:52:54 +01:00
Daniel P. Berrangé
34cb8f6fcd conf: extend domain capabilities for max SEV guest count
There are limits on the number of SEV/SEV-ES guests that can
be run on machines, which may be influenced by firmware
settings. This is important to expose to users.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2021-12-14 16:04:17 +00:00
Daniel P. Berrangé
719bb0bf23 tools: add 'nodesevinfo' virsh command
While some SEV info is reported in the domain capabilities,
for reasons of size, this excludes the certificates. The
nodesevinfo command provides the full set of information.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2021-12-14 16:04:17 +00:00
Daniel P. Berrangé
ac79e9ff5c tools: add 'domlaunchsecinfo' virsh command
This command reports the launch security parameters for
a guest, allowing an external tool to perform a launch
attestation.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2021-12-14 16:04:17 +00:00
Tim Wiederhake
8b6766bd77 docs: domain: Add documentation for hyperv passthrough mode
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-14 16:50:46 +01:00
Tim Wiederhake
ec0616cac3 schema: hyperv: Add mode "passthrough"
This mode will enable all enlightenments known to the hypervisor. See
https://bugzilla.redhat.com/show_bug.cgi?id=1851249

Example:

  <features>
    <hyperv mode='passthrough'/>
    ...
  </features>

Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-14 16:50:45 +01:00
Tim Wiederhake
da9f798445 docs: domain: Add documentation for "hyperv"'s new "mode" attribute
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-14 16:50:45 +01:00
Tim Wiederhake
33d9d3806c schema: Add optional "mode" attribute to hyperv
Allow for an optional attribute "mode", set to the string "custom".

Later patches will introduce different modes. Omitting this attribute
will default to "custom" for backwards compatibility.

Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-14 16:50:45 +01:00
Tim Wiederhake
fa0789cc0c schema: Wrap hyperv element in choice and group
This does not change the schema, but will make upcoming changes
easier.

Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-14 16:50:45 +01:00
Ján Tomko
7624796ac8 docs: use g_auto in virCommand example
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2021-12-14 16:41:36 +01:00
Hyman Huang(黄勇)
5d18d740d8 qemu: support dirty ring feature
Dirty ring feature was introduced in qemu-6.1.0, this patch
add the corresponding feature named 'dirty-ring', which enable
dirty ring feature when starting VM.

To enable the feature, the following XML needs to be added to
the guest's domain description:

<features>
   <kvm>
     <dirty-ring state='on' size='xxx'>
   </kvm>
</features>

If property "state=on", property "size" must be specified, which
should be power of 2 and range in [1024, 65526].

Signed-off-by: Hyman Huang(黄勇) <huangy81@chinatelecom.cn>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2021-12-14 13:17:41 +01:00
Michal Privoznik
16159d5152 qemu: Validate TCG feature is enabled only for TCG domains
After previous commit it's possible for domains to fine tune TCG
features (well, just one - tb-cache). Check that domain has TCG
enabled, otherwise the feature makes no sense.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2021-12-13 17:07:39 +01:00
Michal Privoznik
f106788069 conf: Introduce TCG domain features
It may come handy to be able to tweak TCG options, in this
specific case the size of translation block cache size (tb-size).
Since we can expect more knobs to tweak let's put them under
common element, like this:

  <domain>
    <features>
      <tcg>
        <tb-cache unit='MiB'>128</tb-cache>
      </tcg>
    </features>
  </domain>

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Tested-by: Kashyap Chamarthy <kchamart@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2021-12-13 17:01:02 +01:00
Ján Tomko
4a6b246d39 Revert "virt-ssh-helper: Add manual page"
This was pushed by mistake with incorrect claim of my R-b.

This reverts commit dadcd35260.

Signed-off-by: Ján Tomko <jtomko@redhat.com>
2021-12-10 23:08:31 +01:00
Andrea Bolognani
9402db25f8 virt-pki-query-dn: Add manual page
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-10 18:40:10 +01:00
Andrea Bolognani
823fcba905 virt-qemu-run: Improve manual page
Specifically:

  * use the correct notation and markup for commands, options
    and arguments;
  * rename arguments meta-variables to be more descriptive;
  * sort options so that the most common ones come first;
  * use consistent vertical spacing;
  * fix a typo.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-10 18:39:56 +01:00
Andrea Bolognani
dadcd35260 virt-ssh-helper: Add manual page
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-10 18:39:31 +01:00
Andrea Bolognani
8a637cc766 docs: Update more links to point to the new Go modules
A couple of links were still pointing to the obsolete Go
packages instead of the current module-aware ones.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
2021-12-09 12:16:17 +01:00
Peter Krempa
0f170de28a docs: migration: Add a paragraph about non-shared storage migration
Outline some of the basics and the caveats of the non-shared migration
code.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-07 09:00:39 +01:00
Peter Krempa
8841302e3d docs: Convert 'migration' doc to RST
After conversion the table doesn't have to custom colors, but otherwise
seems to hold well.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-07 09:00:39 +01:00
Peter Krempa
51d1c08fe9 virDomainMigrate: Introduce VIR_MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES flag
Non-shared storage migration of guests which are disk I/O intensive and
have fast local storage may actually never converge if the guest happens
to dirty the disk faster than it can be copied.

This patch introduces a new flag
'VIR_MIGRATE_NON_SHARED_SYNCHRONOUS_WRITES' which will instruct
hypervisors to synchronize local I/O writes with the writes to remote
storage used for migration so that the guest can't overwhelm the
migration. This comes at a cost of decreased local I/O performance for
guests which behave well on average.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-07 09:00:39 +01:00
Peter Krempa
d43513e383 man: virsh: Separate paragraphs describing distinct flags
Separate the paragraphs where the topic changes to simplify further
additions.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-07 09:00:39 +01:00
Peter Krempa
b54c313c33 virDomainBlockCopy: Introduce VIR_DOMAIN_BLOCK_COPY_SYNCHRONOUS_WRITES flag
In cases when the destination storage is slower than the normal VM
storage and the VM does intensive I/O to the disk a block copy job may
never converge.

Switching it to synchronous mode will ensure that all writes done by the
guest are propagated to the destination at the cost of slowing down I/O
of the guest to the synchronous speed.

This patch adds the new API flag and implements virsh support.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-12-07 09:00:39 +01:00
Daniel P. Berrangé
fd0aa7879f conf: add TPM devices to domain capabilities
This adds reporting of available TPM models and backends to the domain
capabilities schema

Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2021-12-01 12:14:03 +00:00
Pavel Hrdina
2fe7622d19 virsh: man: update snapshot-revert description
We've changed the behavior of this API that from now on it will always
restart the VM process and we are no longer able to revert to snapshots
created by libvirt older then 0.9.5.

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2021-11-23 16:03:19 +01:00
Andrea Bolognani
324de132bc docs: Use new URLs for Go modules in downloads page
We've been using the new repositories for a few months now,
but the downloads page still points to the obsolete Go packages.

Fixes: 1832c0a02b
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2021-11-17 17:45:55 +01:00