Commit Graph

3581 Commits

Author SHA1 Message Date
Daniel P. Berrangé
a4da0b2ac6 docs: fix compilation instructions to use separate build dir
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-07-17 17:34:30 +01:00
Andrea Bolognani
fcac6490f2 docs: platforms: Mention Windows API target
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2020-07-14 18:04:13 +02:00
Andrea Bolognani
1b1e3d5f9b docs: platforms: Clarify stance on third-party LTS efforts
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2020-07-14 18:04:10 +02:00
Andrea Bolognani
4ec665d360 docs: platforms: Simplify support policy
We discuss Linux, FreeBSD and macOS separately, and we even go as
far as splitting Linux distros into short-lifetime and long-lifetime,
when ultimately the same two priciples apply everywhere: we don't
want to support a platform longer than its vendor does, and in cases
where the vendor support is extremely long we need to have a
time-based escape hatch.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2020-07-14 18:04:07 +02:00
Andrea Bolognani
a0b02d5095 docs: platforms: Convert to reStructuredText
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2020-07-14 18:04:05 +02:00
Andrea Bolognani
f8d701546f docs: platforms: Add brief outline
This will make the document look nicer, especially after we have
converted it to reStructuredText.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2020-07-14 18:03:54 +02:00
Roman Bogorodskiy
9f78225886 docs: bhyve: document ignoring unknown MSRs
Ignoring unknown MSRs using <features> element
<msrs unknown='ignore'/> was supported for quite some already,
so add documentation for it for completeness of flags coverage,
as some guests can be extra picky about flags passed to bhyve,
and it's useful to know how to control those.

Signed-off-by: Roman Bogorodskiy <bogorodskiy@gmail.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2020-07-14 19:54:01 +04:00
Bastien Orivel
454e5961ab Add a type attribute on the mac address element
This is only used in the ESX driver where, when set to "static", it will
ignore all the checks libvirt does about the origin of the MAC address
(whether or not it's in a VMWare OUI) and forward the original one to
the ESX server telling it not to check it either.

This allows keeping a deterministic MAC address which can be useful for
licensed software which might dislike changes.

Signed-off-by: Bastien Orivel <bastien.orivel@diateam.net>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-07-13 18:47:44 +02:00
Daniel Henrique Barboza
c051e56d27 docs/kbase: introduce migrationinternals.rst
This document describes briefly how Libvirt migration internals
works, complementing the info available in migration.html.in.

Signed-off-by: Daniel Henrique Barboza <danielhb413@gmail.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-07-13 17:18:38 +02:00
Laine Stump
866bb99644 docs: point out that locals should be defined at the top of a block of code
Although we have nothing in make syntax-check to enforce this, and
apparently there are places where it isn't the case (according to
Dan), we should discourage the practice of defining new variables in
the middle of a block of code.

https://www.redhat.com/archives/libvir-list/2020-July/msg00433.html

Signed-off-by: Laine Stump <laine@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2020-07-10 13:42:42 -04:00
Pavel Hrdina
b94856c919 docs: rename fig to svg in Makefile.am
Commit <9ad637c9651ff29955dd6aa8fe31f639b42b7315> converted all fig
files into svg files but did not change the Makefile.am.

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
2020-07-10 17:39:29 +02:00
Pavel Hrdina
9ad637c965 docs: convert FIG files into SVG format
Converted by using:

    fig2dev -L svg <infile> <outfile>

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2020-07-10 16:07:02 +02:00
Pavel Hrdina
062f233b17 docs: drop %.png: %.fig rule
convert bin is part of ImageMagick package and uses uniconvertor to
create png file from fig files.

Unfortunately uniconvertor is python2 only and not available in most
recent distributions which makes the convert command fail with:

sh: uniconvertor: command not found
/usr/bin/mv: cannot stat '/tmp/magick-1397138DRT8Pzx4Qmoc.svg': No such file or directory
convert: delegate failed `'uniconvertor' '%i' '%o.svg'; /usr/bin/mv '%o.svg' '%o'' @ error/delegate.c/InvokeDelegate/1958.
convert: unable to open file `/tmp/magick-1397138S8ARueJXLXkc': No such file or directory @ error/constitute.c/ReadImage/605.
convert: no images defined `docs/migration-managed-direct.png' @ error/convert.c/ConvertImageCommand/3226.

It looks like that there are plans to somehow port uniconvertor into
python3 but as part of different project color-picker but the job is
far from complete.

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2020-07-10 16:07:02 +02:00
Boris Fiuczynski
630ae5d88c docs: kbase: Fix the libvirt-host--validate typo
In f0d0cd6179 I introduced this typo.

Suggested-by: Erik Skultety <eskultet@redhat.com>
Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
2020-07-10 15:04:04 +02:00
Pavel Hrdina
9411bbcd5c docs: remove unused wrapstring.xsl file
Commit <d672551816e106f2ce8a6a04658691db96435fb5> removed last usage of
this file so drop it as well.

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-07-10 09:40:11 +02:00
Pavel Hrdina
caa2545457 docs: remove incorrect generated files by apibuild.py
These files are generated by xsltproc as part of html/index.html and
html/index-%.html rules.

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-07-10 09:40:09 +02:00
Ryan Schmidt
807095fdee Replace "OS-X" with "macOS" in index.html.in
Apple changed the operating system's name from "OS X" to "macOS" a few years ago.

Signed-off-by: Ryan Schmidt <git@ryandesign.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
2020-07-09 09:14:51 +02:00
Erik Skultety
70bb493efc docs: kbase: Fix the libvirt-host-validate typo
I overlooked this typo during review of 2c3ffa37.

Reported-by: Yalan Zhang <yalzhang@redhat.com>
Signed-off-by: Erik Skultety <eskultet@redhat.com>
2020-07-08 13:04:01 +02:00
Michal Privoznik
a89bbbac86 conf: Parse and format HMAT
To cite ACPI specification:

  Heterogeneous Memory Attribute Table describes the memory
  attributes, such as memory side cache attributes and bandwidth
  and latency details, related to the System Physical Address
  (SPA) Memory Ranges. The software is expected to use this
  information as hint for optimization.

According to our upstream discussion [1] this is exposed under
<numa/> as <cache/> under NUMA <cell/> and <latency> or
<bandwidth/> under numa/latencies.

1: https://www.redhat.com/archives/libvir-list/2020-January/msg00422.html

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>
2020-07-08 12:05:24 +02:00
Michal Privoznik
a26f61ee0c Allow NUMA nodes without vCPUs
QEMU allows creating NUMA nodes that have memory only.
These are somehow important for HMAT.

With check done in qemuValidateDomainDef() for QEMU 2.7 or newer
(checked via QEMU_CAPS_NUMA), we can be sure that the vCPUs are
fully assigned to NUMA nodes in domain XML.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>
2020-07-08 12:05:24 +02:00
Jianan Gao
049846b9fd docs: index: Add knowledge base link and description to the index page
Add link and description of libvirt knowledge base to make it easier for
users and testers to understand libvirt.

Signed-off-by: Jianan Gao <jgao@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
2020-07-08 10:21:20 +02:00
Peter Krempa
7e5b993d3b backup: Allow configuring incremental backup per-disk individually
The semantics of the backup operation don't strictly require that all
disks being backed up are part of the same incremental part (when a disk
was checkpointed/backed up separately or in a different VM), or even
they may not have a previous checkpoint at all (e.g. when the disk
was freshly hotplugged to the vm).

In such cases we can still create a common checkpoint for all of them
and backup differences according to configuration.

This patch adds a per-disk configuration of the checkpoint to do the
incremental backup from via the 'incremental' attribute and allows
perform full backups via the 'backupmode' attribute.

Note that no changes to the qemu driver are necessary to take advantage
of this as we already obey the per-disk 'incremental' field.

https://bugzilla.redhat.com/show_bug.cgi?id=1829829

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-07-08 08:40:30 +02:00
Andrea Bolognani
26daf37623 docs: Point to pkg.go.dev instead of godoc.org
The former is the new recommended frontend for browsing Go API
documentation online.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2020-07-07 14:07:33 +02:00
Andrea Bolognani
6a79c7fa88 docs: Use libvirt.org namespace for Go bindings
Fixes: 193ad36406
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2020-07-07 14:07:24 +02:00
Peter Krempa
fc6aaf6a19 conf: backup: Add 'tls' attribute for 'server' element
Allow enabling TLS for the NBD server used to do pull-mode backups. Note
that documentation already mentions 'tls', so this just implements the
schema and XML bits.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-07-07 12:58:19 +02:00
Peter Krempa
d37a2cd5ed qemu: conf: Add configuration of TLS environment for NBD transport of pull-backups
TLS is required to transport backed-up data securely when using
pull-mode backups.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-07-07 12:58:19 +02:00
Peter Krempa
eafd3b3a21 checkpoint: Mention that VIR_DOMAIN_CHECKPOINT_XML_SIZE is expensive and stale
Data is valid only when queried as guest writes may increase the backup
size.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-07-07 12:58:19 +02:00
Peter Krempa
459a60823e docs: checkpoint: Convert XML documentation to RST
Switch to the new format for easier extension.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-07-07 12:58:19 +02:00
Peter Krempa
3927880e9a docs: backup: Convert XML documentation to RST
Switch to the new format for easier extension.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-07-07 12:58:19 +02:00
Andrea Bolognani
c203b8fee1 docs: Update CI documentation
We're no longer using either Travis CI or the Jenkins-based
CentOS CI, but we have started using Cirrus CI.

Mention the libvirt-ci subproject as well, as a pointer for those
who might want to learn more about our CI infrastructure.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2020-07-03 11:00:51 +02:00
Daniel Henrique Barboza
d57f361083 docs: Fix 'Offline migration' description
'transfers inactive the definition of a domain' seems odd.

Signed-off-by: Daniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
2020-07-01 10:05:49 +02:00
Daniel P. Berrangé
764d07838c docs: remove use of the term 'slave' in Jenkins agent docs
Jenkins replaced use of the term 'slave' with 'agent' when
describing its architecture.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-06-26 15:39:34 +01:00
Daniel P. Berrangé
c68a91cc10 docs: update link to the libvirt jenkins plugin
The wiki page we currently link to is just a redirect for
back compat.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-06-26 15:39:34 +01:00
Daniel P. Berrangé
aab0470f0d docs: remove use of the term 'enslaved' wrt tap & bridge devices
Network interfaces are simply attached to a bridge device.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-06-26 15:39:33 +01:00
Daniel P. Berrangé
bec026145d docs: remove use of the term 'whitelist' from firewall docs
The term is redundant in the context used.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-06-26 15:39:28 +01:00
Daniel P. Berrangé
60e4d9d04e docs: remove use of the term 'whitelist' from cgroup docs
The term "access control list" better describes the concept involved.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-06-26 15:38:34 +01:00
Daniel P. Berrangé
5f75ec90fe rpc: remove use of the term 'whitelist' from RPC code
The term "access control list" better describes the concept involved.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-06-26 15:36:40 +01:00
Peter Krempa
c014e11191 kbase: incrementalbackupinternals: Describe 'block commit'
oVirt does merge images out of libvirt in some cases. Add docs outlining
how it's done from a high level.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-06-25 12:24:01 +02:00
Peter Krempa
4d064f9787 kbase: incrementalbackupinternals: Replace bash with pseudocode
Simplify the docs and reduce maintenance burden by just describing the
algorithm by a pseudo-language. Users are encouraged to use libvirt
anyways and projects such as oVirt which do some management of storage
themselves are unlikely to use bash anyways.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-06-25 12:21:13 +02:00
Peter Krempa
abf20e65f7 kbase: incrementalbackupinternals: Add section on 'qemu-img bitmap' use
Define what users should look for when wanting to manipulate bitmaps
themselves.

Later on a patch will turn the bash algorithms into pseudocode for
simplicity.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-06-25 12:21:13 +02:00
Peter Krempa
a4e81e0c32 kbase: incrementalbackupinternals: Add secion on bitmap handling in shell
Add a section that outlines usage of tools to handle bitmaps and
introduce terms corresponding to the output of qemu-img to be used in
further sections.

With this we can simplify the section about checking bitmap health as we
don't have to explain the qemu-img output but can refer to the newly
defined terms.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-06-25 12:21:13 +02:00
Peter Krempa
de56070c9d kbase: incrementalbackupinternals: Clarify language in snapshots section
Emphasize what needs to happen and also that creating a snapshot doesn't
create the appropriate bitmaps. Also mention that granularity is kept.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-06-25 12:21:13 +02:00
Peter Krempa
19061038a7 kbase: incrementalbackupinternals: Add snapshot terminology
Make it obvious what's meant by 'overlay' and 'backing image' for sake
of extension of the document.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-06-25 12:21:13 +02:00
Dmitry Nesterenko
44699edb99 docs: Document recent hook script extension
Signed-off-by: Dmitry Nesterenko <dmitry.nesterenko@virtuozzo.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-06-23 18:34:20 +02:00
Daniel Henrique Barboza
f1d7d6c2cf docs: documentation and schema for the new TPM Proxy model
QEMU 4.1.0 introduced a new device type called TPM Proxy, currently
implemented by PPC64 guests via a new virtual device called
'spapr-tpm-proxy' (see QEMU 0fb6bd073230 for more info).

The TPM Proxy device interacts with a TPM Resource Manager, a host
device capable of multiplexing the host TPM with multiple processes.
This allows multiple guests to access some TPM features at the
same time. Note that this mode of operation does not provide
full TPM features to be available for the guest - for that case
the guest still needs to assign a vTPM device (tpm-spapr for
PPC64 guests). Although redundant, there is currently no technical
limitation for a guest to assign both a vTPM and a TPM Proxy at the
same time.

This patch adds documentation and schema for a new TPM model
type called 'spapr-tpm-proxy' that creates this new TPM Proxy
device. This model is valid only for the 'passthrough' backend.
An example of a TPM Proxy device connected to a TPM Resource Manager
'/dev/tpmrm0' will look like this:

<tpm model='spapr-tpm-proxy'>
  <backend type='passthrough'>
    <device path='/dev/tpmrm0'/>
  </backend>
</tpm>

Tested-by: Satheesh Rajendran <sathnaga@linux.vnet.ibm.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Signed-off-by: Daniel Henrique Barboza <danielhb413@gmail.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2020-06-23 17:24:47 +02:00
Menno Lageman
0e5c919397 conf: add address width attribute to iommu
Add a new aw_bits attribute to the iommu device to control
the address width of the intel-iommu

Signed-off-by Menno Lageman <menno.lageman@oracle.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-06-23 15:51:49 +02:00
Peter Krempa
da5e5a1e15 kbase: Add document outlining internals of incremental backup in qemu
Outline the basics and how to integrate with externally created
overlays. Other topics will continue later.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-06-22 16:11:00 +02:00
Jonathon Jongsma
ed783e5ecd docs: note node device fields that are read-only
As noted by Erik Skultety, we use the same XML schema to report
existing devices and to define new devices. However, some schema
elements are "read-only". In other words, they are used to report
information from the node device driver and cannot be used to define a
new device. Note these in the documentation.

Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-06-19 10:39:55 +02:00
Jonathon Jongsma
c952d9cc1e nodedev: add support for mdev attributes
Mediated devices support arbitrary vendor-specific attributes that can
be attached to a mediated device. These attributes are ordered, and are
written to sysfs in order after a device is created. This patch adds
support for these attributes to the mdev data types and XML schema.

Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-06-19 10:39:54 +02:00
Jonathon Jongsma
9baffe90b5 nodedev: make iommuGroup optional for mdevs
When parsing a nodedev xml file, the iommuGroup element should be
optional. This element should be read-only and is determined by the
device driver. While this is a change to existing behavior, it doesn't
break backwards-compatibility because it makes the parser less strict.

Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2020-06-19 10:39:54 +02:00