The original patches adding the functionality neglected to add any form
of documentation for the stats fields returned for this group.
The stats are directly converted from qemu's 'query-stats(-schema)' QMP
command without any further interpretation. The 'query-stats-schema' has
the following disclaimer:
Note: runtime-collected statistics and their names fall outside QEMU's usual
deprecation policies. QEMU will try to keep the set of available data
stable, together with their names, but will not guarantee stability
at all costs; the same is true of providers that source statistics
externally, e.g. from Linux. For example, if the same value is being
tracked with different names on different architectures or by different
providers, one of them might be renamed. A statistic might go away if
an algorithm is changed or some code is removed; changing a default
might cause previously useful statistics to always report 0. Such
changes, however, are expected to be rare.
Since libvirt is not doing any form of conversion of the stats we can't
meaningfully document any of the returned fields. At the same time we
can't even meaningfully provide any form of API stability for the field
names.
Modify the documentation for the 'VIR_DOMAIN_STATS_VM' group both in the
API docs and in the virsh man page to reflect that and disclaim any form
of stability guarantees we provide normally.
Fixes: 8c9e3dae14
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
There is part of our man page that describes how to switch to the
traditional (non-socket) activation but it might still happens sometimes that
there is an extra --timeout option specified for the daemon.
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
We document that a commit fixing an issue tracked in GitLab
should put just "Fixes: #NNN" into its commit message. But when
viewing git log, having full URL which is directly clickable is
more developer friendly and GitLab is capable of handling both.
Therefore, document that users should put full URL, just like
when fixing a bug tracked in other sites.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Due to the setup of the modular daemon service files the reverting to non-socket
activated daemons could have never worked. The reason is that masking the
socket files prevents starting the daemons since they require (as in Requires=
rather than Wants= in the service file) the sockets. On top of that it creates
issues with some libvirt-guests setups and needlessly increases our support
matrix.
Nothing prevents users to modify their setup in a way that will still work
without socket activation, but supporting such setup only creates burden on our
part.
This technically reverts most of commit 59d30adacd except the change made to
the libvirtd manpage since the monolithic daemon still supports traditional mode
of starting even on systemd.
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
As qemu becomes more modularized, it is important for libvirt to advertise
availability of the modularized functionality through capabilities. This
change adds channel devices to domain capabilities, allowing clients such
as virt-install to avoid using spicevmc channel devices when not supported
by the target qemu.
Signed-off-by: Jim Fehlig <jfehlig@suse.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
As qemu becomes more modularized, it is important for libvirt to advertise
availability of the modularized functionality through capabilities. This
change adds USB redirect devices to domain capabilities, allowing clients
such as virt-install to avoid using redirdev devices when not supported
by the target qemu.
Signed-off-by: Jim Fehlig <jfehlig@suse.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The path() method is deprecated in 0.55.0 and we're recommended
to use full_path() instead. Interestingly, we were already doing
do in couple of places, but not all of them.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The source_root() method is deprecated in 0.56.0 and we're
recommended to use project_source_root() instead.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The build_root() method is deprecated in 0.56.0 and we're
recommended to use project_build_root() instead.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
This option can be used as a shortcut for creating a single XML with
just a CPU model name and no features:
$ virsh hypervisor-cpu-baseline --model Skylake-Server
<cpu mode='custom' match='exact'>
<model fallback='forbid'>Skylake-Server</model>
<feature policy='disable' name='avx512f'/>
<feature policy='disable' name='avx512dq'/>
<feature policy='disable' name='clwb'/>
<feature policy='disable' name='avx512cd'/>
<feature policy='disable' name='avx512bw'/>
<feature policy='disable' name='avx512vl'/>
<feature policy='disable' name='pku'/>
</cpu>
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Even though several CPU models from various vendors are reported as
usable on a given host, user may still want to use only those that match
the host vendor. Currently the only place where users can check the
vendor of each CPU model is our CPU map, which is considered internal
and users should not really be using it directly. So to allow for such
filtering we now advertise the vendor of each CPU model in domain
capabilities.
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Libvirt provides QMP passthrough APIs for the QEMU driver and these are
exposed in virsh. It is not especially pleasant, however, using the raw
QMP JSON syntax. QEMU has a tool 'qmp-shell' which can speak QMP and
exposes a human friendly interactive shell. It is not possible to use
this with libvirt managed guest, however, since only one client can
attach to the QMP socket at any point in time. While it would be
possible to configure a second QMP socket for a VM, it may not be
an known requirement at the time the guest is provisioned.
The virt-qmp-proxy tool aims to solve this problem. It opens a UNIX
socket and listens for incoming client connections, speaking QMP on
the connected socket. It will forward any QMP commands received onto
the running libvirt QEMU guest, and forward any replies back to the
QMP client. It will also forward back events.
$ virsh start demo
$ virt-qmp-proxy demo demo.qmp &
$ qmp-shell demo.qmp
Welcome to the QMP low-level shell!
Connected to QEMU 6.2.0
(QEMU) query-kvm
{
"return": {
"enabled": true,
"present": true
}
}
Note this tool of course has the same risks as the raw libvirt
QMP passthrough. It is safe to run query commands to fetch information
but commands which change the QEMU state risk disrupting libvirt's
management of QEMU, potentially resulting in data loss/corruption in
the worst case. Any use of this tool will cause the guest to be marked
as tainted as an warning that it could be in an unexpected state.
Since this tool introduces a python dependency it is not desirable
to include it in any of the existing RPMs in libvirt. This tool is
also QEMU specific, so isn't appropriate to bundle with the generic
tools. Thus a new RPM is introduced 'libvirt-clients-qemu', to
contain additional QEMU specific tools, with extra external deps.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Add UNDEFINE_TPM and UNDEFINE_KEEP_TPM flags to qemuDomainUndefineFlags()
API and --tpm and --keep-tpm to 'virsh undefine'. Pass the
virDomainUndefineFlagsValues via qemuDomainRemoveInactive()
from qemuDomainUndefineFlags() all the way down to
qemuTPMEmulatorCleanupHost() and delete TPM storage there considering that
the UNDEFINE_TPM flag has priority over the persistent_state attribute
from the domain XML. Pass 0 in all other API call sites to
qemuDomainRemoveInactive() for now.
Signed-off-by: Stefan Berger <stefanb@linux.ibm.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This is a follow-up to fbd6b2480a, adding a link to the latest libvirt
package for openSUSE.
Signed-off-by: Jim Fehlig <jfehlig@suse.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
After some debugging and discussion with systemd team it turns out we
are misusing the ordering in libvirt-guests.service. That happened
because we want to support both monolithic and modular daemon setups and
on top of that we also want to support socket activation and services
without socket activation. Unfortunately this is impossible to express
in the unit file because of how transactions are handled in systemd when
dependencies are resolved and multiple actions (jobs) are queued. For
explanation from Michal Sekletar see comment #7 in the BZ this patch is
fixing:
https://bugzilla.redhat.com/show_bug.cgi?id=1964855#c7
In order to support all the scenarios this patch also amends the
manpages so that users that are changing the default can also read how
to correct the dependency ordering in libvirt-guests unit file.
Ideally we would also keep the existing configuration during upgrade,
but due to our huge support matrix this seems hardly feasible as it
could introduce even more problems.
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
When reconnecting to a running QEMU process, we construct the
per-domain path in all hugetlbfs mounts. This is a relict from
the past (v3.4.0-100-g5b24d25062) where we switched to a
per-domain path and we want to create those paths when libvirtd
restarts on upgrade.
And with namespaces enabled there is one corner case where the
path is not created. In fact an error is reported and the
reconnect fails. Ideally, all mount events are propagated into
the QEMU's namespace. And they probably are, except when the
target path does not exist inside the namespace. Now, it's pretty
common for users to mount hugetlbfs under /dev (e.g.
/dev/hugepages), but if domain is started without hugepages (or
more specifically - private hugetlbfs path wasn't created on
domain startup), then the reconnect code tries to create it.
But it fails to do so, well, it fails to set seclabels on the
path because, because the path does not exist in the private
namespace. And it doesn't exist because we specifically create
only a subset of all possible /dev nodes. Therefore, the mount
event, whilst propagated, is not successful and hence the
filesystem is not mounted. We have to do it ourselves.
If hugetlbfs is mount anywhere else there's no problem and this
is effectively a dead code.
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>
In the basic configuration with monolithic libvirtd users are required
to also start virtlogd. Add a general note with a specific example
hinting that this is needed.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
To prevent surprises when a build doesn't in fact contain the required
functionality suggest that users force-enable required modules.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
