When external swtpm support was added back in 9.0.0, I omitted
the update of the XML docs.
Add it now, especially since the 'emulator' backend can now
also use the <source> element.
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Some models are just aliases to other models. Make this relation
available to users via domain capabilities.
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Nikolai Barybin <nikolai.barybin@virtuozzo.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
The previous example will cause the error like:
error: Options --file and --base64 are mutually exclusive
Reported-by: Yanqiu Zhang <yanqzhan@redhat.com>
Signed-off-by: Han Han <hhan@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
When a VM is being migrated to a destination host it can be made
persistent on the destination by using '--persistent'. That may not
work as intended if '--xml' is used as well as that allows overriding
certain aspects of the VM xml, but does not involve the persistent
definition. In most cases users will need to supply also
'--persistent-xml' with the same set of modification.
Modify the man page to clarify the above so that users don't end up with
broken VM after migrating and restarting it.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
When virtio-(non-)transitional models were introduced, the
documentation was updated to include them; at the same time,
language was introduced indicating that using the existing
virtio model is no longer recommended.
This is unnecessarily harsh, and has resulted in people
incorrectly believing (through no fault of their own) that the
virtio model has been deprecated.
In reality, it's perfectly fine to use the virtio model as the
stress-free option that, while often not producing the ideal
PCI topology, will generally get the job done and work reliably
across libvirt versions and machine types.
Tweak the documentation so that it hopefully carries the
desired message across.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Get the JSON profile that the swtpm instance was created with from the
output of 'swtpm socket --tpm2 --print-info 0x20 --tpmstate ...'. Get the
name of the profile from the JSON and set it in the current and persistent
emulator descriptions as 'name' attribute and have the persistent
description stored with this update. The user should avoid setting this
'name' attribute since it is meant to be read-only. The following is
an example of how the XML could look like:
<profile source='local:restricted' name='custom:restricted'/>
If the user provided no profile node, and therefore swtpm_setup picked its
default profile, the XML may now shows the 'name' attribute with the name
of the profile. This makes the 'source' attribute now optional.
<profile name='default-v1'/>
Signed-off-by: Stefan Berger <stefanb@linux.ibm.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Add documentation for the TPM backend profile node and point the reader to
further documentation about TPM profiles available in the swtpm man page.
Signed-off-by: Stefan Berger <stefanb@linux.ibm.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
virtiofs 1.11 contains support for migration so update the 'Note' which
states that migration is not supported.
Additionally mention that VM snapshots don't save state of the files
shared via virtiofs so reverting is not a good idea.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Currently the qemu firmware code weirdly depends on the 'format' field
of the nvram image itself to do the auto-selection process as well as
then uses it to declare the actual type to qemu.
As it's not technically required that the template and the on disk image
share the type introduce a 'templateFormat' field which will split off
from the shared purpose of the type and will be used for the selection
and instantiation process, while 'format' will be left for the actual
type of the on disk image.
This patch introduces the field, adds XML infrastructure as well as
plumbs it to the firmware bits.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The NVRAM template file may be autoselected same as the loader/firmware
image. Add a hint that this can occur and also that it doesn't
necessarily need to be from the 'qemu.conf' configured files.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
When using recent Fedora and RHEL versions, the manual setup that
is otherwise necessary to enable the module can be replaced with
executing a single command.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The page contains some confusing information, especially around
limitations that supposedly only affect one of the two variants,
and goes into what is arguably an unnecessary amount of detail
when it comes to its inner workings.
We can make the page a lot shorter and snappier without
affecting its usefulness, so let's do just that.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
As requested on the libvirt users list I am adding this mention to the
apps page.
Reported-by: Erik Huelsmann <ehuels@gmail.com>
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Learn to parse a directory for the TPM state.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Learn to parse a file path for the TPM state.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Stefan Berger <stefanb@linux.ibm.com>
Domain capabilities include information about support for various
devices and models.
Panic devices are not included in the output which means that management
applications need to include the logic for choosing the right device
model or request a default model and try defining such a domain.
Add reporting of panic device models into the domain capabilities based
on the logic in qemuValidateDomainDefPanic() and also report whether
panic devices are supported based on whether at least one model is
supported. That way consumers of the domain capability XML can
differentiate between libvirt not reporting the panic device models or
no model being supported.
Resolves: https://issues.redhat.com/browse/RHEL-65187
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The support for the 'sgio' attribute for SCSI-backed devices was dropped
as there wasn't really ever any upstream support for it.
The docs do state that support for this depends on the hypervisor
itself, but we can be more clear that there is no hypervisor which does
support it.
There is also a suggestion to use 'sgio' instead of 'rawio' as being
more "secure" but since it no longer works drop this suggestion.
Resolves: https://issues.redhat.com/browse/RHEL-65268
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The docs for submitting a patch describe using your "Legal Name" with
the Signed-off-by line.
In recent times, there's been a general push back[1] against the notion
that use of Signed-off-by in a project automatically requires / implies
the use of legal ("real") names and greater awareness of the downsides.
Full discussion of the problems of such policies is beyond the scope of
this commit message, but at a high level they are liable to marginalize,
disadvantage, and potentially result in harm, to contributors.
TL;DR: there are compelling reasons for a person to choose distinct
identities in different contexts & a decision to override that choice
should not be taken lightly.
A number of key projects have responded to the issues raised by making
it clear that a contributor is free to determine the identity used in
SoB lines:
* Linux has clarified[2] that they merely expect use of the
contributor's "known identity", removing the previous explicit
rejection of pseudonyms.
* CNCF has clarified[3] that the real name is simply the identity
the contributor chooses to use in the context of the community
and does not have to be a legal name, nor birth name, nor appear
on any government ID.
Since we have no intention of ever routinely checking any form of ID
documents for contributors[4], realistically we have no way of knowing
anything about the name they are using, except through chance, or
through the contributor volunteering the information. IOW, we almost
certainly already have people using pseudonyms for contributions.
This proposes to accept that reality and eliminate unnecessary friction,
by following Linux & the CNCF in merely asking that a contributors'
commonly known identity, of their choosing, be used with the SoB line.
[1] Raised in many contexts at many times, but a decent overall summary
can be read at https://drewdevault.com/2023/10/31/On-real-names.html
[2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=d4563201f33a022fc0353033d9dfeb1606a88330
[3] https://github.com/cncf/foundation/blob/659fd32c86dc/dco-guidelines.md
[4] Excluding the rare GPG key signing parties for regular maintainers
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
When a CPU model is reported as usable='no' an additional
<blockers model='...'> element is added for that CPU model to show which
features are missing for the CPU model to become usable.
Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Mention that hypervisors may need a temporary file and document the qemu
template for creating them.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
The migration parameter causes zero detection to be enabled and zero
blocks are *not* transferred to the destination. This means that users
must provide pre-cleared images that read all zero, otherwise the
non-zero blocks on destination which reside in places where the source
has zero blocks would be kept intact corrupting the image.
As not transferring and overwriting the zero blocks is what the feature
is supposed to do the users need to provide the proper environment.
Document the requirement, both in API and in the virsh man page for the
'--migrate-disks-detect-zeroes' option.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
With watchdog action=dump the actual watchdog action is set to pause and
the daemon then proceeds to dump the process. After that the domain is
resumed. That was the case since the feature was added. However the
resuming of the domain might be unexpected, especially when compared to
HW watchdog, which will never run the guest from the point where it got
interrupted.
Document the pre-existing behaviour, since any change might be
unexpected as well. Change of behaviour would require new options like
dump+reset, dump+pause, etc. That option is still possible, but
orthogonal to this change.
Resolves: https://issues.redhat.com/browse/RHEL-753
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
Enforce that relative links are used within the page, so that local
installations don't require internet conection and/or don't redirect to
the web needlessly.
This is done by looking for any local link (barring exceptions) when
checking links with 'check-html-references.py'.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Now that most things were migrated out of the old server which hosted
the 'libvirt.org' web (now handles only 'https://download.libvirt.org')
which no longer even hosts the cgit web interface (any link redirects to
gitlab) the whole section now is obsolete. Remove it.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Replace full/external links which point to content within
'https://libvirt.org/' with relative links so that the web page works
fully locally.
This does not change the links in 'docs/manpages' as we want the
installed man page to work from everywhere (even when the local docs are
not installed) and the generated API docs which take links from the C
source.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Add a '--require-https' switch to 'check-html-references' helper script
which will error out if any non-https external link is used from our web
and use it while builidng docs.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The documentation about remote access to libvirt was pointing to a blog
post about usage of the 'ssh-agent' to avoid being asked for passwords.
The blog/host is now unfortunately defunct thus the link is dead.
Replace the link by the official man page of the 'ssh-agent' program.
This convenietnly removes the last non-'https' link on our web.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Expose the new parameter as '--migrate-disks-detect-zeroes' option.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
The meaning of the values as well as their maximums are hard to predict
and accounting for all the possibilities (which by the way might change
during daemon's execution) is borderline hallucinatory. There is
already a way we represent them, which is the same as the Linux kernel.
We do not interpret them at all, just blindly use them. In order to
make this more apparent for the users change the documentation for the
<memorytune/> (not <memtune/>) element more boldly.
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Enhance the 'since' annotation of <filterref> documentation to note
it's only supported by the QEMU, LXC, and ch hypervisor drivers.
Suggested-by: Demi Marie Obenour <demi@invisiblethingslab.com>
Signed-off-by: Jim Fehlig <jfehlig@suse.com>
Reviewed-by: Laine Stump <laine@redhat.com>
qemu supports this enlightenment since version 7.10.
From the qemu commit:
Hyper-V specification allows to pass parameters for certain hypercalls
using XMM registers ("XMM Fast Hypercall Input"). When the feature is
in use, it allows for faster hypercalls processing as KVM can avoid
reading guest's memory.
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
qemu supports this enlightenment since version 7.10.
From the qemu commit:
The newly introduced enlightenment allow L0 (KVM) and L1 (Hyper-V)
hypervisors to collaborate to avoid unnecessary updates to L2
MSR-Bitmap upon vmexits.
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
This introduces a new 'ps2' feature which, when disabled, results in
no implicit PS/2 bus input devices being automatically added to the
domain and addition of the 'i8042=off' machine option to the QEMU
command-line.
A notable side effect of disabling the i8042 controller in QEMU is that
the vmport device won't be created. For this reason we will not allow
setting the vmport feature if the ps2 feature is explicitly disabled.
Signed-off-by: Kamil Szczęk <kamil@szczek.dev>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This will allow to print full domains info:
Id Name State UUID
---------------------------
Signed-off-by: Nikolai Barybin <nikolai.barybin@virtuozzo.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Based on discussion after commit f432114d9c was pushed it was pointed
out that the documentation still mentions the older version.
Fix the documentation to state the new version and introduce ambiguity
for future updates.
Fixes: f432114d9c
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Add dma_translation attribute to iommu to enable/disable dma traslation
for intel-iommu
Signed-off-by: Sandesh Patel <sandesh.patel@nutanix.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Introduced only a couple of commits ago (in
v10.5.0-84-g90e50e67c6) the pstore device acts as a nonvolatile
storage, where guest kernel can store information about crashes.
This device, however, expects a file in the host from which the
crash data is read. So far, we expected users to provide a path,
but we can autogenerate one if missing. Just put it next to
per-domain's NVRAM stores.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
The aim of pstore device is to provide a bit of NVRAM storage for
guest kernel to record oops/panic logs just before the it
crashes. Typical usage includes usage in combination with a
watchdog so that the logs can be inspected after the watchdog
rebooted the machine. While Linux kernel (and possibly Windows
too) support many backends, in QEMU there's just 'acpi-erst'
device so stick with that for now. The device must be attached to
a PCI bus and needs two additional values (well, corresponding
memory-backend-file needs them): size and path. Despite using
memory-backend-file this does NOT add any additional RAM to the
guest and thus I've decided to expose it as another device type
instead of memory model.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Kristina Hanicova <khanicov@redhat.com>
New element 'openfiles' had confusing name. Since the patch with
this new element wasn't propagate yet, old name ('rlimit_nofile')
was changed.
...
<binary>
<openfiles max='122333'/>
</binary>
...
Signed-off-by: Adam Julis <ajulis@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
User feedback has shown that the examples are not clear enough
to illustrate the cli passthrough concept in action.
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Add an element to configure the rlimit nofile size:
...
<binary>
<rlimit_nofile size='122333'/>
</binary>
...
Non-positive values are forbidden in 'domaincommon.rng'. Added separate
test file, created by modifying the 'vhost-user-fs-fd-memory.xml'.
Signed-off-by: Adam Julis <ajulis@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
If mgmt apps on top of libvirt want to make a decision on the
backend type for <interface type='user'/> (e.g. whether past is
supported) we currently offer them no way to learn this fact.
Domain capabilities were invented exactly for this reason. Report
supported net backend types there.
Now, because of backwards compatibility, specifying no backend
type (which translates to VIR_DOMAIN_NET_BACKEND_DEFAULT) means
"use hyperviosr's builtin SLIRP". That behaviour can not be
changed. But it may happen that the hypervisor has no support for
SLIRP. So we have to report it.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
In order to learn what types of <launchSecurity/> are supported
users can turn to domain capabilities and find <sev/> and
<s390-pv/> elements. While these may expose some additional info
on individual launchSecurity types, we are lacking clean
enumeration (like we do for say device models). And given that
SEV and SEV SNP share the same basis (info found under <sev/> is
applicable to SEV SNP too) we have no other way to report SEV SNP
support.
Therefore, report supported launchSecurity types in domain
capabilities.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
