1
0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-25 01:34:11 +03:00
Commit Graph

4397 Commits

Author SHA1 Message Date
Peter Krempa
b64a9e97d1 docs: compiling: Separate 'prepare', 'configure', and 'build' steps
Only the preparation of sources differs between a build from a git
checkout vs a build from tarball. Restructure the docs to outline the
difference and combine information on how to configure libvirt.

Most notably the suggestion to use '-Dsystem=true' was present only for
the steps to build a git checkout.

Suggest also running the testsuite as part of the build step.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-09-13 13:36:49 +02:00
Peter Krempa
dae224fdb1 docs: compiling: Separate information on how to install libvirt and add disclaimer
Create a section for instructions on how to install the built binaries
rather than mentioning it multiple times.

Add a note that installing over your distro-provided packages will most
likely break your instalation.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-09-13 13:36:49 +02:00
Peter Krempa
91284a2893 docs: compiling: Section off block on how to run from build directory
Running from build directory isn't strictly tied to the git-checkout
build so make a new section for it.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-09-13 13:36:49 +02:00
Peter Krempa
fbd6b2480a docs: compiling: Add a paragraph suggesting installation from repository
Users should be encouraged to install libvirt from the distro's repos in
the first place.

Also encourage distro-specific ways to get newer versions, rather than
building from source manually.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-09-13 13:36:49 +02:00
Michal Privoznik
d3397885d5 kbase: Document QEMU private mount NS limitations
There are two points I've taken for granted:

  1) the mount points are set before starting a guest,
  2) the / and its submounts are marked as shared, so that mount
     events propagate into child namespaces when assumption 1) is
     not held.

But what's obvious to me might not be obvious to our users.
Document these known limitations.

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2123196
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
2022-09-12 12:05:07 +02:00
Kristina Hanicova
4435c026b7 qemu & conf: move BeginAsyncJob & EndAsyncJob into src/conf
Signed-off-by: Kristina Hanicova <khanicov@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
2022-09-07 12:15:06 +02:00
Kristina Hanicova
421f1e749f qemu & conf: move BeginAgentJob & EndAgentJob into src/conf/virdomainjob
Although these and functions in the following two patches are for
now just being used by the qemu driver, it makes sense to have all
begin job functions in the same file.

Signed-off-by: Kristina Hanicova <khanicov@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
2022-09-07 12:14:43 +02:00
Kristina Hanicova
9085ccbfb4 qemu: use virDomainObjEndJob()
This patch moves qemuDomainObjEndJob() into
src/conf/virdomainjob as universal virDomainObjEndJob().

Signed-off-by: Kristina Hanicova <khanicov@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
2022-09-07 12:14:07 +02:00
Kristina Hanicova
0d22febfc6 qemu: use virDomainObjBeginJob()
This patch moves qemuDomainObjBeginJob() into
src/conf/virdomainjob as universal virDomainObjBeginJob().

Signed-off-by: Kristina Hanicova <khanicov@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
2022-09-07 12:13:30 +02:00
Peter Krempa
4328018bd0 schema: nodedev: Fix schema attribute value for the 'vport_ops' capability
The code (since 448be8f706) useds 'vport_ops' in XML.
Later commit cc17f09246 added schema for 'vports_ops' (extra 's').
Fix the schema and the corresponding docs.

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2121262
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-09-01 13:11:09 +02:00
Peter Krempa
99d533c2aa docs: newapi: Consider also 'https://' links in the API generator XSL
We converted exclusively to https links so the generator should wrap
those in appropriate link tags too.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Jonathon Jongsma <jjongsma@redhat.com>
2022-09-01 13:11:09 +02:00
Peter Krempa
d4f7850d5b Remove support for building the sheepdog storage driver backend
The sheepdog project is unmaintained, with last commit in 2018 and
numerous unanswered issues reported.

Remove the libvirt storage driver support for it to follow the removal
of the client support in qemu.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Claudio Fontana <cfontana@suse.de>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-09-01 13:11:09 +02:00
Peter Krempa
c8ee79346a spec: Drop libvirt-daemon-driver-storage-sheepdog package
Upstream will be dropping the sheepdog storage backend, so we need to
stop building the package and obsolete it.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Claudio Fontana <cfontana@suse.de>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-09-01 13:11:09 +02:00
Carlos Bilbao
b2dce59302 docs: formatdomain: Fix small typos and syntax errors
Fix some small typos and syntax errors in file formatdomain.rs.

Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
2022-08-25 18:58:08 +02:00
Martin Kletzander
6457619d18 Rename iterface type='dummy' to type='null'
When commit bac6b266fb added this "functionality" this was the only
naming I could think of, but after discussion with Dan we found the name
'null' fits a bit better, so change it before we make a release with the
old name.

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-08-25 13:27:04 +02:00
Daniel P. Berrangé
206b59a296 docs: fix syntax errors in IPv6 NAT example XML
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2022-08-23 16:33:20 +01:00
Martin Kletzander
0225483adc conf, docs, schemas: Add support for interface type vds
This represents an interface connected to a VMWare Distributed Switch,
previously obscured as a dummy interface.

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-08-18 08:34:31 +02:00
Lin Ma
d81ae1f244 docs: Fix missing slashes in the maxphysaddr example
Signed-off-by: Lin Ma <lma@suse.com>
Reviewed-by: Jim Fehlig <jfehlig@suse.com>
2022-08-17 08:16:23 -06:00
Peter Krempa
0da0304818 qemu: Formally deprecate support for qemu < 4.2
Per [1] the Debian 10 reaches EOL in August of 2022. This allows us to
bump the minimum supported qemu version to qemu-4.2 which will also
allow us to do significant cleanups.

This commit bumps the minimum qemu verison and updates the corresponding
docs.

[1]: https://wiki.debian.org/DebianReleases

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-08-11 14:38:31 +02:00
Martin Kletzander
bac6b266fb conf, docs: Add support for dummy network interface
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-08-05 14:37:54 +02:00
Andrea Bolognani
550bf7682d kbase: Document how to disable Secure Boot entirely
In most cases, disabling the secure-boot or the enrolled-keys
firmware feature will achieve the same result: allowing an
unsigned operating system to run.

Right now we're only documenting the latter configuration. Add
the former as well, and explain the difference between the two.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-08-04 14:39:18 +02:00
Andrea Bolognani
18249f278a kbase: Always explicitly enable secure-boot firmware feature
It should be enough to enable or disable the enrolled-keys feature
to control whether Secure Boot is enforced, but there's a slight
complication: many distro packages for edk2 include, in addition
to general purpose firmware images, builds that are targeting the
Confidential Computing use case.

For those, the firmware descriptor will not advertise the
enrolled-keys feature, which will technically make them suitable
for satisfying a configuration such as

  <os firmware='efi'>
    <firmware>
      <feature state='off' name='enrolled-keys'/>
    </firmware>
  </os>

In practice, users will expect the general purpose build to be
used in this case. Explicitly asking for the secure-boot feature
to be enabled achieves that result at the cost of some slight
additional verbosity.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-08-04 14:39:11 +02:00
Dario Faggioli
e6c29f09e5 conf: Add support for specifying CPU max physical address size
This patch introduces the

    <maxphysaddr mode='passthrough'/>
    <maxphysaddr mode='emulate' bits='42'/>

sub element of /domain/cpu, which allows specifying the guest virtual CPU
address size. This can be useful if the guest needs to have a large amount
of memory.

If mode='passthrough', the virtual CPU will have the same number of address
bits as the host. If mode='emulate', the mandatory bits attribute specifies
the number of address bits.

Signed-off-by: Dario Faggioli <dfaggioli@suse.com>
Signed-off-by: Jim Fehlig <jfehlig@suse.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2022-08-04 09:04:07 +02:00
Daniel P. Berrangé
578ac25c6a conf: support stateless UEFI firmware
Normally when an UEFI firmware is marked as read-only, an associated
NVRAM file will be created. Some builds of UEFI firmware, however, wish
to remain stateless and so will be read-only, but never have any NVRAM
file. To represent this concept a 'stateless' tristate bool attribute
is introduced on the <loader/> element.

There are rather a large number of permutations to consider.

With default firmware selection

  *  <os/>

     => Historic default, no change

  *  <os>
       <loader stateless='yes'/>
     </os>

     => Explicit version of historic default, no change

  *  <os>
       <loader stateless='no'/>
     </os>

      => Invalid, bios is always stateless

With manual legacy BIOS selection

  *  <os>
       <loader>/path/to/seabios</loader>
       ...
     </os>

     => Historic default, no change

  *  <os>
       <loader stateless='yes'>/path/to/seabios</loader>
       ...
     </os>

     => Explicit version of historic default, no change

  *  <os>
       <loader stateless='no'>/path/to/seabios</loader>
       ...
     </os>

      => Invalid, bios is always stateless

With manual UEFI selection

  *  <os>
       <loader type='pflash'>/path/to/edk2</loader>
       ...
     </os>

     => Historic default, no change

  *  <os>
       <loader type='pflash' stateless='yes'>/path/to/edk2</loader>
       ...
     </os>

     => Skip auto-filling NVRAM / template

  *  <os>
       <loader type='pflash' stateless='no'>/path/to/edk2</loader>
       ...
     </os>

     => Explicit version of historic default, no change

With automatic firmware selection

  *  <os firmware='bios'/>

     => Historic default, no change

  *  <os firmware='bios'>
       <loader stateless='yes'/>
     </os>

     => Explicit version of historic default, no change

  *  <os firmware='bios'>
       <loader stateless='no'/>
     </os>

      => Invalid, bios is always stateless

  *  <os firmware='uefi'/>

     => Historic default, no change

  *  <os firmware='uefi'>
       <loader stateless='yes'/>
     </os>

     => Skip auto-filling NVRAM / template

  *  <os firmware='uefi'>
       <loader stateless='no'/>
     </os>

     => Explicit version of historic default, no change

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-26 15:41:44 +01:00
Peter Krempa
429c15259c docs: Add article about handling upstream issues
Outline how upstream issues are triaged and explain what the states of
the issue means.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
2022-07-26 16:35:57 +02:00
Peter Krempa
80e50315b4 docs: patches: Add a note about reviews and contacting developers
Add a note outling best practices around review and responding to it.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
2022-07-26 16:35:57 +02:00
Michal Privoznik
32b9d4390e coding-style: Allow some use of ternary operators
While we all understand that excessive use of ternary operator
may worsen code readability (e.g. nested, multi-line expression),
there are few cases where using it actually improves code
readability. For instance, when a function takes a long list of
arguments out of which one depends on a boolean expression, or
when formatting "yes"/"no" or "on"/"off" values based on a
boolean variable (although one can argue that the latter is a
subset of the former). Just consider alternatives to:

  virBufferAsprintf(buf, "<elem>%s</elem>\n", boolVar ? "yes" : "no");

In fact, this pattern occurs plenty in our code. Exempt it from
our "no ternary operators" rule.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Claudio Fontana <cfontana@suse.de>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-26 08:48:48 +02:00
Michal Privoznik
9e8601c464 lib: Use G_NO_INLINE instead of G_GNUC_NO_INLINE
The G_GNUC_NO_INLINE macro will eventually be marked as
deprecated [1] and we are recommended to use G_NO_INLINE instead.
Do the switch now, rather than waiting for compile time warning
to occur.

1: 15cd0f0461
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
2022-07-18 17:23:15 +02:00
Tim Wiederhake
57d263d6a3 docs: Fix typos
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
2022-07-18 11:10:55 +02:00
Erik Skultety
c341989fa1 docs: ci: Add a brief section on how to run the CI workload locally
This is just a glue to the testing article introduced in previous
commits.

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-15 08:26:38 +02:00
Erik Skultety
659ac70281 docs: ci: Add a section on how to add a new platform to libvirt CI
Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-15 08:26:34 +02:00
Erik Skultety
294b5a9821 docs: ci: Add info about the two major types of jobs our CI runs
Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-15 08:26:29 +02:00
Erik Skultety
4df9845bb9 docs: Change the CI headline from "CI Testing" to "CI"
It's not just strategy the master CI article talks (or will talk in the
future) about.

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-15 08:26:25 +02:00
Erik Skultety
77ab90f0a2 docs: Drop the testsuites article
The article was replaced with a new one in previous commit, so we don't
need this one anymore.

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-15 08:26:25 +02:00
Erik Skultety
200ab55980 docs: Replace testsuites article with the new 'testing' article
The new article provides more in-depth information on testing options
in libvirt.

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-15 08:26:25 +02:00
Erik Skultety
5d9e41ee77 docs: Provide an article on testing
Currently we don't have much information on how testing is done in
libvirt and the little we have is scattered among multiple files. This
patch creates a common landing page containing all important bits about
testing in libvirt, providing links to respective sections which
deserve their own articles.

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-15 08:26:13 +02:00
Erik Skultety
1dc037ec17 docs: Provide an article on how to add a custom runner to the project
Since running our functional test suite in GitLab cannot make use of
the shared resources it makes sense to document the process of adding
own HW to run the custom libvirt executor that powers the integration
suite. This article will likely make even more sense in the future with
GitLab severely cutting down on shared CI resources.

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-14 17:31:21 +02:00
Erik Skultety
0be5de986a docs: Provide more information about the TCK test suite
Most importantly, how to get it, how install dependencies and how
to run it.

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-14 17:31:21 +02:00
Erik Skultety
983cf8c03b docs: Move the CI dashboard to its own RST module
The dashboard itself simply takes away focus from everything else that
makes sense to have in the CI article, so move it to it's own article
and link it from the main CI article.

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-14 17:31:21 +02:00
Michal Privoznik
85ea114016 conf: Introduce @guestReset to hostdev's <source/>
Some USB devices have a buggy firmware that either crashes on
device reset, or make the device unusable in some other way.
Fortunately, QEMU offers a way to skip device reset either
completely, or if device is not initialized yet. Expose this
ability to users under:

    <hostdev mode='subsystem' type='usb'>
      <source guestReset='off'/>
    </hostdev>

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-07-13 16:00:50 +02:00
Daniel P. Berrangé
c748000cd1 docs: replace ARRAY_CARDINALITY with G_N_ELEMENTS
Fix docs illustrating call with an obsolete macro.

Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-13 12:18:06 +01:00
Daniel P. Berrangé
497d8555c4 docs: add info about factors affecting CPU compatibility
While libvirt solves most of the problem of ensuring compatibility, when
there is incompatibility it can be hard for users to track down the
cause. Everything knows to check the physical CPU model, but there are a
surprisingly large number of other factors influencing compatibility.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2022-07-13 11:04:29 +01:00
Michal Privoznik
1277a9c884 domcaps: Introduce TPM backendVersion
We accept TPM version in the domain XML. However, supported
version depends on the host (swtpm_setup binary) and thus it may
be tricky for users (or mgmt applications) chose a version.
Introduce machinery for reporting supported version in domain
capabilities.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2022-07-13 11:55:06 +02:00
Michal Privoznik
6a00c565c4 docs: Document TPM portion of domcaps
Surprisingly, we don't document TPM part of domain capabilities.
Fortunately, the information exposed is pretty much self
explanatory, but we should document it regardless.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2022-07-13 11:55:06 +02:00
Peter Krempa
b7e05cf966 docs: formatstorage: Format XML namespace definition as code block
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
2022-07-12 11:33:37 +02:00
Peter Krempa
c37ebda93a kbase: debuglogs: Add a note about auto-shutdown of daemons
When using runtime setting of logging with 'virt-admin' it can be
confusing that the settings are discarded when the shutdown timeout of a
daemon is reached.

Add a note about this behaviour along with a suggestion to use
virt-admin to disable the behaviour if needed.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2022-07-07 14:35:30 +02:00
Peter Krempa
fe69f5074a virt-admin: Introduce 'daemon-timeout'
Add a simple command to drive the new 'virAdmConnectSetDaemonTimeout'
API.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2022-07-07 14:35:30 +02:00
Han Han
2ee82b3dfb docs: Fix syntax error in defaultiothread example
Signed-off-by: Han Han <hhan@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2022-07-07 12:14:02 +02:00
Michal Privoznik
92678703ce docs: Document <address/> for IOMMU device
The commit v8.3.0-rc1~199 introduced <address/> to <iommu/>
device. And while it updated the RNG it forgot to update the
docs. Fix that.

Fixes: b0eb1e193f
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
2022-07-04 13:21:16 +02:00
Tim Wiederhake
58e6bb8be8 Fix spelling
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
2022-07-04 10:07:47 +02:00