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>
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>
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>
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>
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>
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>
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>
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>
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>
Fix docs illustrating call with an obsolete macro.
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
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>
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>
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>
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>
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>
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>
Treat the 'protocolVer' field as a string so that e.g. '4.1' can be
used. Forbid only ',' in the string as it's a separator of arguments for
mount options.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Provide simple recipes for the most common high-level tasks.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Document the format of the 'readahead' and 'timeout' XML elements more
accurately.
Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The mailman for mailing lists hosted by Red Hat seems to have moved
to listman.redhat.com. While the old links still seem to work,
point our docs to the new location to avoid the redirect.
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
While you can chain the virsh output up to a later 'xmllint' or 'xpath'
command, integrating it into virsh avoids needs for installing extra
binaries which we've often found to be missing on production installs
of libvirt. It also gives better response if the initial virsh command
hits an error, as you don't get an aborted pipeline.
$ virsh pool-dumpxml --xpath //permissions default
<permissions>
<mode>0711</mode>
<owner>1000</owner>
<group>1000</group>
<label>unconfined_u:object_r:svirt_home_t:s0</label>
</permissions>
If multiple nodes match, they are emitted individually:
$ virsh dumpxml --xpath '//devices/*/address[@type="pci"]' --wrap demo
<address type="pci" domain="0x0000" bus="0x05" slot="0x00" function="0x0"/>
<address type="pci" domain="0x0000" bus="0x03" slot="0x00" function="0x0"/>
...snip...
<address type="pci" domain="0x0000" bus="0x00" slot="0x02" function="0x0" multifunction="on"/>
<address type="pci" domain="0x0000" bus="0x07" slot="0x00" function="0x0"/>
but if intending to post-process the output further, the results
can be wrapped in a parent node
$ virsh dumpxml --xpath '//devices/*/address[@type="pci"]' --wrap demo
<nodes>
<address type="pci" domain="0x0000" bus="0x05" slot="0x00" function="0x0"/>
<address type="pci" domain="0x0000" bus="0x03" slot="0x00" function="0x0"/>
...snip...
<address type="pci" domain="0x0000" bus="0x00" slot="0x02" function="0x0" multifunction="on"/>
<address type="pci" domain="0x0000" bus="0x07" slot="0x00" function="0x0"/>
</nodes>
Fixes https://gitlab.com/libvirt/libvirt/-/issues/244
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Add an element to configure the thread pool size:
...
<binary>
<thread_pool size='16'/>
</binary>
...
https://bugzilla.redhat.com/show_bug.cgi?id=2072905
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Update the default "driver" value for hostdev interface since
the default is not "KVM" anymore (refer to "Host device
asssignment" part and by test results). And update the mac
address in one xml example.
Signed-off-by: Yalan Zhang <yalzhang@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
This patch introduces the logic to format and parse remote NVRAM.
Update NVRAM element schema, and docs for supporting network backed
NVRAM. NVRAM backed over network would give the flexibility to start
the VM on any host without having to worry about where to get the latest
nvram image.
<nvram type='network'>
<source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/0'>
<host name='example.com' port='6000'/>
</source>
</nvram>
or
<nvram type='file'>
<source file='/var/lib/libvirt/nvram/guest_VARS.fd'/>
</nvram>
In the qemu driver we will support the new definition only with qemu's
supporting -blockdev.
Signed-off-by: Prerna Saxena <prerna.saxena@nutanix.com>
Signed-off-by: Florian Schmidt <flosch@nutanix.com>
Signed-off-by: Rohit Kumar <rohit.kumar3@nutanix.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Tested-by: Rohit Kumar <rohit.kumar3@nutanix.com>
As of v7.0.0-877-g70ac26b9e5 QEMU exposes its default event loop
for devices with no IOThread assigned as an QMP object. In the
very next commit (v7.0.0-878-g71ad4713cc) it was extended for
thread-pool-min and thread-pool-max attributes. Expose them under
new <defaultiothread/> element.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Since virsh implements a wrapper over virDomainSetIOThreadParams()
(command iothreadset) let's wire up new typed parameters there too.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
At least in case of QEMU an IOThread is actually a pool of
threads (see iothread_set_aio_context_params() in QEMU's code
base). As such, it can have minimal and maximal number of worker
threads. Allow setting them in domain XML.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Certain documentation bits tried to put a reference of a value into
quotes, but that's not needed for both the pure view of the rST source
and the rendered output.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
In many cases we move around or rename internal anchors which may break
links leading to the content.
docutils handle the case of links inside a document, but we are lacking
the same form of checking between documents.
Introduce a script which cross-checks all the anchors and links in HTML
output files and prints problems and use it as a test case for the
'docs' directory.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The link was most likely broken when 'formatsecret' was converted to
RST.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
When uri.html was converted to RST the 'URI remote' anchor was not fixed
in remote.rst.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Most of the links were broken by moving the article into kbase, but in
this case we need to also fix the anchor names.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Certain links were missing the '../' prefix to reach files in the parent
directory from the time the page was introduced.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The links were broken when the documentation was moved into the
'internals' subdirectory.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
While the links work they'd trip up the link validator script which will
be added later.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The link was not fixed when the page was moved into 'kbase/'
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The links were broken on the initial conversion of formatdomain.html to
RST which didn't faithfully forward port some of the manually added
anchors.
Fix it by pointing to the closest possible heading.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Remove what seems like links from some headings. This error predates the
conversion to RST where an '<a href' was used instead of '<a id' in the
source document.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Some links didn't exit the 'kbase/' directory and 'virDomainBackupEnd'
API never existed.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Once we are already using the new anchor format we can create the link
via a local reference.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The role was used to pass through raw HTML to define custom anchor
names. Since all of the document was now converted to use the anchors
generated from headers we can remove it.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
One local reference required rewording of a whole paragraph to make
sense.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Some rewording and rewraping was needed to accomodate the new local
references.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The surrounding paragraph around the only fixed use was rewrapped.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The one local link addition prompted rewrapping of the whole paragraph.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
All local links were reformulated to make sense with local references.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Two paragraphs containing local links were reformulated and rewrapped.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The MinGW-w64 project has effectively replaced the original
MinGW project, and distributions such as Fedora have been shipping
packages based on the former for years now.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The project is developed as part of GNOME these days, and the
old URL redirects to GNOME's GitLab instance.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
GNU netcat was last updated in 2004. These days, most operating
systems will include either the nmap or OpenBSD variant of the
tool.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The website is still up, but the software itself was last
updated in 2014.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The website is still up, although the latency is so high that it
could hardly considered usable; the software itself was last
updated in 2015.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
It doesn't seem to be a current product: there is no proper
website for it, and the most recent installation instructions
I've been able to locate are targeted at RHEL 6.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Move the internal documentation about qemu threading to the knowledge
base.
The conversion included rstizing of the text document, mainly just
fixing of the headline and enclosing function names and code examples
into code block sections.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
In the qemu driver certain configs such as disk throttling or CPU
hotplug is configured by interacting with the monitor at the startup
phase of the hypervisor and thus is not part of the "native config".
Add a paragraph into the documentation outlining that the native
configuration might not be completely usable.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
The 'absolute' clock offset type has a 'start' attribute which is an
unix epoch timestamp to which the hardware clock is always set at start
of the VM.
This is useful if some VM needs to be kept set to an arbitrary time for
e.g. testing or working around broken software.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Add these XML formats validation in manpage or script:
cpu, domainbackup, domaincaps, domaincheckpoint, networkport,
storagepoolcaps.
Signed-off-by: Han Han <hhan@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
The qemu-vdagent channel is introduced since:
"05b09f039e conf: add qemu-vdagent channel"
It will be in the version 8.4.0.
Signed-off-by: Han Han <hhan@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Add the ability to configure a qemu-vdagent in guest domains. This
device is similar to the spice vdagent channel except that qemu handles
the spice-vdagent protocol messages itself rather than routing them over
a spice protocol channel.
The qemu-vdagent device has two notable configuration options which
determine whether qemu will handle particular vdagent features:
'clipboard' and 'mouse'.
The 'clipboard' option allows qemu to synchronize its internal clipboard
manager with the guest clipboard, which enables client<->guest clipboard
synchronization for non-spice guests such as vnc.
The 'mouse' option allows absolute mouse positioning to be sent over the
vdagent channel rather than using a usb or virtio tablet device.
Sample configuration:
<channel type='qemu-vdagent'>
<target type='virtio' name='com.redhat.spice.0'/>
<source>
<clipboard copypaste='yes'/>
<mouse mode='client'/>
</source>
</channel>
Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Useful for knowing how to construct the XML and debugging.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Most of the anchors that were forward ported to formatdomain.rst when it
was converted are not actually referenced by our documentation. Since
it's now quite some time after the conversion was done we can remove
them.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Modify the gitlab templates linking to it and remove the raw HTML.
Note that also the default template needs to be changed directly in
gitlab.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Modify the name of the 'IRC discussion' paragraph to just 'IRC' so that
the links keep working and remove the raw HTML anchors.
Adjustment is needed for documents which were using the '#email' anchor
which has now become '#mailing-lists'.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The 'codeofconduct' anchor is unused as of 523f2de82e .
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Avoid the table and add a brief description of the transport protocol.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Add a new heading 'Local hypervisor URIs' and move the sections about
'qemu', 'xen' and 'test' under it.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Mention the legacy 'xen' string usage under the Xen hypervisor uri
section.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
We now have an paragraph about default URI choice if the passed pointer
is NULL. Add the two related bits from the 'NULL and empty string URIs'
from the legacy section to the current one and remove the old stuff.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Adjust links in the process.
Note that the conversion to the table is temporary and upcoming patch
will modify it for better readability.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The paragraph talks about lack of fine grained access control which was
already added a long time ago.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
When the setup of TLS certs was originally split out of
'docs/remote.html' ( df99aa311a ) links refering to it were not
fixed.
Adjust them to point to the correct document.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The anchor name was not fixed when the 'formatstorage' document was
converted to rst.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The conversion also included a change to the layout of the document.
Specifically the individual 'capabilty' types are now separated under
individual headings rather than part of the original definition list.
This reduces nesting but also esures that proper anchors are generated
automatically.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Additionally hyperlinks in other parts of the documentation are updated
to match.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Also adjust direct links from other pages.
Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Original conversion didn't properly convert local links. Fix them by
pointing to the section name. In certain cases this requires
reformulation of the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Original conversion didn't properly convert local links. Fix them by
pointing to the section name. In certain cases this requires
reformulation of the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Original conversion didn't properly convert local links. Fix them by
pointing to the section name. In certain cases this requires
reformulation of the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Original conversion didn't properly convert local links. Fix them by
pointing to the section name. In certain cases this requires
reformulation of the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Original conversion didn't properly convert local links. Fix them by
pointing to the section name. In certain cases this requires
reformulation of the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Original conversion didn't properly convert local links. Fix them by
pointing to the section name. In certain cases this requires
reformulation of the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Original conversion didn't properly convert local links. Fix them by
pointing to the section name. In certain cases this requires
reformulation of the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Original conversion didn't properly convert local links. Fix them by
pointing to the section name. In certain cases this requires
reformulation of the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Original conversion didn't properly convert local links. Fix them by
pointing to the section name. In certain cases this requires
reformulation of the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Docutils-0.17 switched to using <main> instead of a <div
class='document'> and <section> instead of <div class='section'>.
To ensure that our pages still work we need to slightly adapt our XSL
stylesheet to select the <main> tag properly and adapt the CSS to also
select the 'section' element instead of a class and to apply to a <main>
tag with the appropriate names.
Docutils-0.17 also changed to use 'h2' for section heading instead of
'h1'.
Note the styles applied to the 'main' element with certain id can't be
made more universal by just applying to the id itself, as in certain
cases (e.g. 'documentation') we also have sections with that name. This
was previously ensured by also matching the 'document' class which would
make it equal to the 'main' element.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
Select direct 'h1' children of elements named 'knowledge-base' and
'documentation. It's simpler and will also work properly with
docutils-0.17 and later where we don't have a div with class 'document'
wrapping everything.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
Commit 42d36b65a3 added new fields to the API docs but didn't add the
virsh man page equivalent.
Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2073867
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
While the content is slightly outdated it's still a good primer on how
an API call traverses through the client library and to the remote
driver.
To make the page useful, this commit:
- removes the paragraphs which were intended to serve as a directory
page for the 'internals' subdirectory
- adds a note saying that some facts might not be up to date
- adds linking to this page from the kbase directory page
- adds more monospace formatting around function names
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Note that this document was not referenced from any top level page. This
patch does a straight conversion and leaves it unreferenced.
Next patch will then modify it to serve as an overview (hence the new
name) of how an API call happens.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
All documents were now moved away so we don't need this any more.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Along with the conversion we need to adapt the stylesheets to apply to
the new document similarly to how we do that in the knowledge base.
Note that one visible difference is that now a 'Documentation' heading
is visible on top of the page.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Add an 'internals' subfolder to 'docs/kbase' to house all the documents
under internals. The output files are still under 'docs/kbase'.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Historically we had two top level XSL files for top level and nested
documents which only differ in what they pass for 'href_base' to the
main 'page.xsl' file.
We can instead pass the variable as argument from the build system so
that we have just one XSL file and also allow for more nested document
trees in the future.
The '404' page is special even with the current XSL way so we add a
special case for it.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Add a separate column of documents regarding internals of libvirt and
move the 'migrationinternals' and 'incrementalbackupinternals' pages
under the new heading.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The enumeration of functions and types supported by the bindings was
moved to the 'README.rst' file in the 'libvirt-csharp' repo:
https://gitlab.com/libvirt/libvirt-csharp/-/merge_requests/8
Remove the corresponding bits from the main repository.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
Note that links from the first table leading to sections of this
document further below were removed for simplicity.
Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
The KVM device assignment was removed in v5.7.0-rc1~103 but virsh
and its manpage still mention it. Don't do that.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Added "rss" and "rss_hash_report" configuration that should be
used with qemu virtio RSS. Both options are triswitches. Used as
"driver" options and affects only NIC with model type "virtio".
In other patches - options should turn on virtio-net RSS and hash
properties.
Signed-off-by: Andrew Melnychenko <andrew@daynix.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
As of April 23 2022, Ubuntu 20.04 will be out for two years, which means
we no longer have to support Ubuntu 18.04 along with qemu-2.11 shipped
with it.
This then brings the minimum qemu version we have to support to
qemu-3.1:
Debian 10/Stable: 3.1
OpenSUSE Leap 15.3: 5.2
Ubuntu 20.04: 4.2
RHEL/Centos 8.4: 4.2
Next event in this space will be 2023/07/06 when Debian 11 will be out
for two years.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The 'debuglogs' knowledge base page has way more info and examples on
how to set logging use it instead of the ad-hoc examples.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Use backticks to force monospace font instead of double quotes.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
The top level heading didn't contain the word 'port'.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Fix the referenced anchor in 'formatdomain.rst' right away.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
The first sentence was moved up a paragraph to stop treating the first
sub-heading as a page subtitle.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Instead of creating an empty object and then setting keys one
at a time, it is possible to pass a dict object to
configuration_data(). This is nicer because it doesn't require
repeating the name of the cfg_data object over and over.
There is one exception: the 'conf' object, where we store values
that are used directly by C code. In that case, using a dict
object is not feasible for two reasons: first of all, replacing
the set_quoted() calls would result in awkward code with a lot
of calls to format(); moreover, since code that modifies it is
sprinkled all over the place, refactoring it would probably
make things more complicated rather than simpler.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
In 0895a0e, it was noted that the "sockets" value in the topology
section of capabilities reflects not the number of sockets per NUMA
node, not the total number.
Unfortunately, the fix was applied to the wrong place: the domain XML
format documentation, not that for the capabilities output. And, in
fact, the domain XML interprets "sockets" as the total number, not a
per-node value.
Back out this change in favour of a note in the capabilities
documentation instead.
Fixes: 0895a0e75d
Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: John Levon <john.levon@nutanix.com>
Upcoming patches will add possibility to override configuration of a
device with custom properties as a more versatile replacement to using
QEMU's '-set' parameter, which doesn't work when we use JSON to
instantiate devices.
Describe the XML used for the override as well as expectations of
upstream support in case something breaks.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This reverts commit 150540394d.
Turns out, this feature is not needed and QEMU will fix TSC
without any intervention from outside.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>P
Some versions of Windows hang on reboot if their TSC value is greater
than 2^54. The workaround is to reset the TSC to a small value. Add
to the domain configuration an attribute for this. It can be used
by QEMU and in principle also by ESXi, which has a property called
monitor_control.enable_softResetClearTSC as well.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Since its v5.0.0 release QEMU is capable of specifying number of
threads used to allocate memory. It defaults to 1, which may be
too low for humongous guests with gigantic pages.
In general, on QEMU cmd line level it is possible to use
different number of threads per each memory-backend-* object, in
practical terms it's not useful. Therefore, use <memoryBacking/>
to set guest wide value and let all memory devices 'inherit' it,
silently. IOW, don't introduce per device knob because that would
only complicate things for a little or no benefit.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
schemas are used for more than just documentation,
virsh edit fails if schemas are not available.
Therefore, fix the no-docs build by moving schemas/
to the parsing code inside src/conf/.
Signed-off-by: Claudio Fontana <cfontana@suse.de>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
The idea of the manual mode is to allow a synchronized snapshot in cases
when the storage is outsourced to an unmanaged storage provider which
requires cooperation with snapshotting.
The mode will instruct the hypervisor to pause along when the other
components are snapshotted and the 'manual' disk can be snapshotted
along. This increases latency of the snapshot but allows them in
otherwise impossible situations.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
I introduced support for these vim plugins several years ago
but have since moved away from them. These days developers
are likely better served by lsp-based tooling, which doesn't
require additional per-project configuration.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
In cases when the hostname of the NBD server doesn't match the hostname
in the TLS certificate the new attribute 'tlsHostname' can be used to
override it.
Add the XML infrastructure and tests.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Document our usage of GitLab and the read-only mirrors.
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
With the introduction of smart HTTP protocol in git 1.6.6,
the only advantage of plain git:// over https:// is not
having the encryption overhead.
Remove the reference to git://, assuming the overhead
is neligible compared to the value of screen space
on the downloads page.
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
While the mirrors themselves are still available, the gitweb
interface on libvirt.org has been disabled.
The mirrors can still be accessible via, e.g.:
git clone https://libvirt.org/git/libvirt-python.git
But such link gives a 404 error. Remove the links from the website
to avoid confusion.
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The table was manually converted to a set of 'list-table'-s for better
experience of viewing the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The security label setting for the external images is part of the
'source' element and documented there. Remove the empty definition added
accidentally in commit ac88a8cfad
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
In blockdev mode we support creating snapshots on all kinds of storage
that qemu allows us to format the image. Drop the part of the sentence
enumerating explicitly supported protocols.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
There was another paragraph describing the attribute 'type' of the
'disk' element under the description of the subelements. Move it to the
top to get all relevant information in one place.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The 'Branch fixing policy' paragraph claims that we have at least one
actively maintained stable branch which isn't currently the case.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The examples contain some whitespace and command prompts which just
waste space.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Also update the link from 'formatstorageencryption' to the
'usage-type-volume' anchor.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Extra care is taken to preserve the 'codeofconduct' anchor which is used
in our page template. Upcoming patch will change that but we'll retain
the anchor.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Special care is given to preserve the 'quality' anchor in the 'bugs'
page as we link to it directly from the gitlab issue template.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The page is not referenced from anywhere and contains dead links for the
output and links to old repos.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The page isn't linked from anywhere and the project was archived.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Our last default template had a match of "node()" which incidentally matched
everything, including text nodes. Since this has the same priority according to
the XSLT spec, section 5.5:
https://www.w3.org/TR/1999/REC-xslt-19991116#conflict
this is an error. Also according to the same spec section, the XSLT processor
may signal the error or pick the last rule.
This was uncovered with libxslt 1.1.35 which contains the following commit:
b0074eeca3
which makes the build fail with:
runtime error: file ../docs/page.xsl line 223 element element
xsl:element: The effective name '' is not a valid QName.
because our last rule also matches text nodes and we are trying to extract the
node name out of them.
To fix this we change the match to "*" which only matches elements and not all
the nodes, and to avoid any possible errors with different XSLT processors we
also bump the priority of the match="text()" rule a little higher, just in case
someone needs to use an XSLT processor that chooses signalling the error instead
of the optional recovery.
https://bugs.gentoo.org/833586
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Extend domdirtyrate-calc virsh api with mode option, either
of these three options "page-sampling,dirty-bitmap,dirty-ring"
can be specified when calculating dirty page rate.
Signed-off-by: Hyman Huang(黄勇) <huangy81@chinatelecom.cn>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The systemd version in RHEL-7 lacked support for the LISTEN_FDNAMES env
variable with socket activation. Since we stopped targetting RHEL-7 we
can drop some considerable amount of compatibility code.
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
The repositories containing them are usually offered with lower
guarantees, so we don't consider them when it comes to figuring
out the minimum targeted version of our dependencies.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
There are dupliacated and non-continuous CPU IDs used in HMAT
example. Fix that.
Signed-off-by: Jing Qi <jinqi@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This wires up support for resetting NVRAM for all APIs that allow
this feature.
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
As the parent address is part of the mdev nodedev name lets expose the
internally available parent address in the XML.
Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Most people will want to use isa-debugcon to obtain debug output
for SeaBIOS / EDK II, so let's include a ready-made example for
that scenario in our documentation.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Introduce support for
<serial type='pty'>
<target type='isa-debug'>
<model type='isa-debugcon'/>
</target>
<address type='isa' iobase='0x402'/>
</console>
which is used as a way to receive debug messages from the
firmware on x86 platforms.
Note that the default port is hypervisor specific, with QEMU
currently using 0xe9 since that's the original Bochs debug port.
For use with SeaBIOS/OVMF, the iobase port needs to be explicitly
set to 0x402.
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Outline information commonly logged which users could consider
sensitive.
Add a note that VNC/SPICE passwords are logged in plaintext.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Many domain elements have "QEMU and KVM only" or "QEMU/KVM since x.y.z"
remarks. Most of the elements work for HVF domain, so it makes sense to
add respective notices for HVF domain.
All the elements have been manually tested.
Signed-off-by: Roman Bolshakov <r.bolshakov@yadro.com>
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Tested-by: Brad Laue <brad@brad-x.com>
Tested-by: Christophe Fergeau <cfergeau@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
It's worth to make the domain type a little bit more visible than a row
in news. An example of hvf domain is available on QEMU driver page.
While at it, mention Hypervisor.framework on index page.
Signed-off-by: Roman Bolshakov <r.bolshakov@yadro.com>
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Tested-by: Brad Laue <brad@brad-x.com>
Tested-by: Christophe Fergeau <cfergeau@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
QEMU supports Hypervisor.framework since 2.12 as hvf accel.
Hypervisor.framework provides a lightweight interface to run a virtual
cpu on macOS without the need to install third-party kernel
extensions (KEXTs).
It's supported since macOS 10.10 on machines with Intel VT-x feature
set that includes Extended Page Tables (EPT) and Unrestricted Mode.
Signed-off-by: Roman Bolshakov <r.bolshakov@yadro.com>
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Tested-by: Brad Laue <brad@brad-x.com>
Tested-by: Christophe Fergeau <cfergeau@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
An update to meson 0.61.1 meant that it started showing warnings due to the fact
that the default for run_command's 'check' parameter is going to change. It
unveiled the fact that we were even missing that parameter in some calls where
we expected different outcome. To make sure the behaviour does not change
specify the parameter explicitly. In places where we check for the return code
the parameter should be 'false' so that meson does not fail. In all other cases
the parameter should be set to 'true' to make sure possible failure also stops
meson.
The warning in meson was added in https://github.com/mesonbuild/meson/pull/9304
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Tim Wiederhake <twiederh@redhat.com>
Hint users that they can use 'virt-admin' also for the new monolithic
daemons.
Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2038045
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Modular daemons are now the default in many new installations, thus we
need to include steps how to determine that modular daemons are used and
modular-daemon specific locations for the config files and admin URIs.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Since we are at a transition period where some users may be running
monolithic libvirtd and others already the modular topology we need a
section that allows users to figure out which is in use.
This will be particularly important in the document about enabling
logging, as the active log file depends on which daemon is in use.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
The socket permissions are controlled by 'unix_sock_admin_perms', but
regardless the code requires that 'geteuid() != clientuid' to allow
clients thus it doesn't make sense to make users aware of it.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
It's the only GIF file we have in our repository.
We could convert it to PNG, but that would result in a
significantly bigger file (~5.5 KiB vs ~1.5 KiB).
Since the image doesn't really add much to the documentation,
drop it instead.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
When invoking 'virsh guestinfo $VM' without explicitly specifying a
group of information to return, virsh always reports success even when
the guest agent doesn't report any information in the current state.
This is desired in situations when you are okay with stats being missing
and avoids spurious errors being reported.
Clarify that this is really desired in the man page.
Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2041665
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
It's a tool name so use backticks to format it in monospace.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Move out the settings required to pre libvirt-4.4.0 deployments into a
separate section so that the main point is not cluttered by now mostly
irrelevant settings.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Enabling the logs is the focus of this article. Decouple it from the
first section.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Use the heading hierarchy as generated by pandoc which we use in most
of the converted XML format docs.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
This was not mentioned before.
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
This partially reverts commit 9ccbed6afb.
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
sysconfig files are owned by the admin of the host. They have the
liberty to put anything they want into these files. This makes it
difficult to provide different built-in defaults.
Remove the sysconfig file and place the current desired default into
the service file.
Local customizations can now go either into /etc/sysconfig/name
or /etc/systemd/system/name.service.d/my-knobs.conf
Attempt to handle upgrades in libvirt.spec.
Dirty files which are marked as %config will be renamed to file.rpmsave.
To restore them automatically, move stale .rpmsave files away, and
catch any new rpmsave files in %posttrans.
Signed-off-by: Olaf Hering <olaf@aepfle.de>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
This unclutters the top-level docs directory.
Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
To make it easier for users to figure out how the DN should be formatted.
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
This removes a dead link, the need for users to understand a glib function and a
improper reference to fnmatch (as we only expand asterisks to any string).
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
This should make the documentation less confusing mainly for
Ceph people.
Signed-off-by: Or Ozeri <oro@il.ibm.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The new parameter group returns information about network interfaces
Signed-off-by: zhanglei <zhanglei@smartx.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Extend the TPM backend XML with a node 'active_pcr_banks' that allows a
user to specify the PCR banks to activate before starting a VM. Valid
choices for PCR banks are sha1, sha256, sha384 and sha512. When the XML
node is provided, the set of active PCR banks is 'enforced' by running
swtpm_setup before every start of the VM. The activation requires that
swtpm_setup v0.7 or later is installed and may not have any effect
otherwise.
<tpm model='tpm-tis'>
<backend type='emulator' version='2.0'>
<active_pcr_banks>
<sha256/>
<sha384/>
</active_pcr_banks>
</backend>
</tpm>
Fixes: https://bugzilla.redhat.com/show_bug.cgi?id=2016599
Signed-off-by: Stefan Berger <stefanb@linux.ibm.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Presumably the result of a copy/paste mistake, the the argument for the
`nodedev-start` command was described as a 'network' rather than a
'device'.
Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
QEMU version 3.1 introduced PV_SEND_IPI CPUID feature bit under
commit 7f710c32bb8 (target-i386: adds PV_SEND_IPI CPUID feature bit).
This patch adds a new KVM feature 'pv-ipi' to disable this feature
(enabled by default). Newer CPU platform (Ex, AMD Zen2) supports
hardware accelation for IPI in guest, to use this feature to get
better performance in some scenarios. Detailed about the discussion:
https://lkml.org/lkml/2021/10/20/423
To disable kvm-pv-ipi and have libvirt add "-cpu host,kvm-pv-ipi=off"
to the QEMU command line, the following XML code needs to be added to the
guest's domain description:
<features>
<kvm>
<pv-ipi state='off'/>
</kvm>
</features>
Signed-off-by: zhenwei pi <pizhenwei@bytedance.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This reverts commit 7300ccc9b3.
Signed-off-by: Laine Stump <laine@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Ani Sinha <ani@anisinha.ca>
The meson 0.60.0 release introduced a bug with the '/' operator when
using an empty path component. '/foo' / '' will now result in '/foo'
not '/foo/'
https://github.com/mesonbuild/meson/issues/9450
This breaks libvirt because xsltproc requires the trailing '/' on the
output directory path. Fortunately the explicit 'join_paths' function
is not affected by the regression
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This commit extends libvirt XML configuration to support luks2 encryption format.
This means that <encryption format="luks2" engine="librbd"> becomes valid.
Currently librbd is the only engine that supports this new format.
Signed-off-by: Or Ozeri <oro@il.ibm.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
rbd encryption is new in qemu 6.1.0.
This commit adds a new encryption engine property which
allows the user to use this new encryption engine.
Signed-off-by: Or Ozeri <oro@il.ibm.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
This commit extends libvirt XML configuration to support a custom encryption engine.
This means that <encryption format="luks" engine="qemu"> becomes valid.
The only engine for now is qemu. However, a new engine (librbd) will be added in an upcoming commit.
If no engine is specified, qemu will be used (assuming qemu driver is used).
Signed-off-by: Or Ozeri <oro@il.ibm.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Describes the format of the newly added VPD capability and gives and
example for a real-world device.
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Dmitrii Shcherbakov <dmitrii.shcherbakov@canonical.com>
* XML serialization and deserialization of PCI VPD;
* PCI VPD capability flags added and used in relevant places;
* XML to XML tests for the added capability.
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Dmitrii Shcherbakov <dmitrii.shcherbakov@canonical.com>
Issuing simple QMP commands is pain as they need to be wrapped by the
JSON wrapper:
{ "execute": "COMMAND" }
and optionally also:
{ "execute": "COMMAND", "arguments":...}
For simple commands without arguments we can add syntax sugar to virsh
which allows simple usage of QMP and additionally prepares also for
passing through of the 'arguments' section:
virsh qemu-monitor-command $VM query-status
is equivalent to
virsh qemu-monitor-command $VM '{"execute":"query-status"}'
and
virsh qemu-monitor-command $VM query-named-block-nodes '{"flat":true}'
or
virsh qemu-monitor-command $VM query-named-block-nodes '"flat":true'
is equivalent to
virsh qemu-monitor-command $VM '{"execute":"query-named-block-nodes", "arguments":{"flat":true}}'
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Some people from Red Hat does not use 'redhat.com' domain emails.
They use personal or other domains.
Signed-off-by: Julio Faracco <jcfaracco@gmail.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This change introduces a new libvirt sub-element <pci> under
<features> that can be used to configure all pci related features.
Currently the only sub-sub element supported by this sub-element is
'acpi-bridge-hotplug' as shown below:
<features>
<pci>
<acpi-bridge-hotplug state='on|off'/>
</pci>
</features>
The above option is only available for the QEMU driver, for x86 guests
only. It is a global option, affecting all PCI bridge controllers on
the guest.
The 'acpi-bridge-hotplug' option enables or disables ACPI hotplug
support for cold-plugged pci bridges. Examples of bridges include the
PCI-PCI bridge (pci-bridge controller) for pc (i440fx) machinetypes,
or PCIe-PCI bridges and pcie-root-port controllers for q35
machinetypes.
For pc machinetypes in x86, this option has been available in QEMU
since version 2.1. Please see the following changes in qemu repo:
9e047b982452c6 ("piix4: add acpi pci hotplug support")
133a2da488062e ("pc: acpi: generate AML only for PCI0 devices if PCI
bridge hotplug is disabled")
For q35 machinetypes, this was introduced in QEMU 6.1 with the
following changes in qemu repo:
(a) c0e427d6eb5fef ("hw/acpi/ich9: Enable ACPI PCI hot-plug")
(b) 17858a16950860 ("hw/acpi/ich9: Set ACPI PCI hot-plug as default on
Q35")
The reasons for enabling ACPI based hotplug for PCIe (q35) based
machines (as opposed to native hotplug) are outlined in (b). There are
use cases where users would still want to use native
hotplug. Therefore, this config option enables users to choose either
ACPI based hotplug or native hotplug for bridges (for example for pcie
root port controller in q35 machines).
Qemu capability validation checks have also been added along with
related unit tests to exercise the new conf option.
Signed-off-by: Ani Sinha <ani@anisinha.ca>
Reviewed-by: Laine Stump <laine@redhat.com>
This change introduces libvirt xml support to enable/disable hotplug on the
pci-root controller. It adds a 'target' subelement for the pci-root controller
with a 'hotplug' property. This property can be used to enable or disable
hotplug for the pci-root controller. For example, in order to disable hotplug
on the pci-root controller, one has to use set '<target hotplug='off'>' as
shown below:
<controller type='pci' model='pci-root'>
<target hotplug='off'/>
</controller>
'<target hotplug='on'>' option would enable hotplug for pci-root controller.
This is also the default value. This option is only available for pc machine
types and is applicable for qemu/kvm accelerator only.This feature was
introduced from qemu version 5.2 with the following change in qemu repository:
3d7e78aa7777f ("Introduce a new flag for i440fx to disable PCI hotplug on the root bus")
The above qemu commit describes some reasons why users might to disable hotplug
on PCI root buses.
Related unit tests to exercise the new conf option has also been added.
Signed-off-by: Ani Sinha <ani@anisinha.ca>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Laine Stump <laine@redhat.com>
This commit adds new memorydevices.rst page which should serve
all models of memory devices. Yet, I'm documenting virtio-mem
quirks only.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
New 'update-memory-device' command is introduced which aims on
making it user friendly to change <memory/> device. So far I just
need to change <requested/> so I'm introducing --requested-size
only; but the idea is that this is extensible for other cases
too. For instance, want to change <myElement/>? A new
--my-element argument can be easily introduced.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The virtio-mem has another property that isn't exposed yet:
current size exposed to the guest. Please note, that this is
different to <requested/> because esp. on sizing the memory
down guest may refuse to release some blocks. Therefore, let's
have another size to report in the XML. But because of its
nature, the <current/> won't be parsed and is report only (for
live XMLs).
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The virtio-mem is paravirtualized mechanism of adding/removing
memory to/from a VM. A virtio-mem-pci device is split into blocks
of equal size which are then exposed (all or only a requested
portion of them) to the guest kernel to use as regular memory.
Therefore, the device has two important attributes:
1) block-size, which defines the size of a block
2) requested-size, which defines how much memory (in bytes)
is the device requested to expose to the guest.
The 'block-size' is configured on command line and immutable
throughout device's lifetime. The 'requested-size' can be set on
the command line too, but also is adjustable via monitor. In
fact, that is how management software places its requests to
change the memory allocation. If it wants to give more memory to
the guest it changes 'requested-size' to a bigger value, and if it
wants to shrink guest memory it changes the 'requested-size' to a
smaller value. Note, value of zero means that guest should
release all memory offered by the device. Of course, guest has to
cooperate. Therefore, there is a third attribute 'size' which is
read only and reflects how much memory the guest still has. This
can be different to 'requested-size', obviously. Because of name
clash, I've named it 'current' and it is dealt with in future
commits (it is a runtime information anyway).
In the backend, memory for virtio-mem is backed by usual objects:
memory-backend-{ram,file,memfd} and their size puts the cap on
the amount of memory that a virtio-mem device can offer to a
guest. But we are already able to express this info using <size/>
under <target/>.
Therefore, we need only two more elements to cover 'block-size'
and 'requested-size' attributes. This is the XML I've came up
with:
<memory model='virtio-mem'>
<source>
<nodemask>1-3</nodemask>
<pagesize unit='KiB'>2048</pagesize>
</source>
<target>
<size unit='KiB'>2097152</size>
<node>0</node>
<block unit='KiB'>2048</block>
<requested unit='KiB'>1048576</requested>
</target>
<address type='pci' domain='0x0000' bus='0x00' slot='0x04' function='0x0'/>
</memory>
I hope by now it is obvious that:
1) 'requested-size' must be an integer multiple of
'block-size', and
2) virtio-mem-pci device goes onto PCI bus and thus needs PCI
address.
Then there is a limitation that the minimal 'block-size' is
transparent huge page size (I'll leave this without explanation).
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The value of zero is valid <unique_id/> (see
virNodeDeviceGetSCSIHostCaps()) but our RNG does not think so.
Switching the type to 'unsignedInt' does allow value of zero.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
A nodedev can have 'scsi_generic' capabilities but corresponding
RNG is missing. Fortunately, it's very simple - there's only one
mandatory child element <char/>.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The <type/> element for <capability type='scsi'> part of nodedev
XML is optional (see udevProcessSCSIDevice()) and as such might
not be formatted into nodedev XML (see
virNodeDeviceCapSCSIDefFormat()). Reflect this in our RNG.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
The option "queue-size" for virtio-blk was added in qemu-2.12.0, and
default value increased from qemu-5.0.0.
However, increasing this value may lead to drop of random access
performance.
Signed-off-by: Hiroki Narukawa <hnarukaw@yahoo-corp.jp>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Add up-to-date information about creating and defining mediated devices
in libvirt.
Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Bring the documentation for nodedev-list up to date with the latest
code, especially documenting the --active and -all options.
Also add documentation for the nodedev-define, nodedev-undefine, and
nodedev-start commands.
Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
When documenting our public API in some places we use '@' to
refer to the variable. For instance:
* This API tries to set guest time to the given value. The time
* to set (@seconds and @nseconds) should be in seconds relative
* to the Epoch of 1970-01-01 00:00:00 in UTC.
However, when generating HTML documentation these tokens are
copied verbatim. What we can do is drop the '@' character and
wrap the variable in <code/> so that it is formatted properly.
Due to the way we 'parse' docs a token might actually be slightly
more than just '@variable'. For instance in the example above we
will have the following tokens: '(@seconds' and '@nseconds)'.
Thus we need to handle possible substring before and after
variable.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
This is currently the only way to view the 'autostart' property for a
node device in virsh.
Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Add ability to set node devices to autostart on boot or parent device
availability.
Signed-off-by: Jonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
In the example for <memory model='dimm'/> we show how to
configure hugepages as backend. In the example we show 4MiB
hugepages which are non-standard and thus at the first glance may
mislead users thinking that a regular sized pages (4K) will be
used. Use 2MiB as the value instead.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
The virtiofs project started off using "virtio-fs" but later switched to
the "virtiofs" spelling because it matches the spelling of the mount -t
virtiofs command-line. Update the kbase article with the new spelling so
it matches the virtiofs website.
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
A number of legacy issues make the virtiofs kbase article hard to
understand. Most users don't need to configure NUMA or a memory backend
other than memfd. Move that information to the bottom of the article so
the recommended syntax is most prominent.
Suggested-by: Richard W.M. Jones <rjones@redhat.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Richard W.M. Jones <rjones@redhat.com>
Signed-off-by: Ján Tomko <jtomko@redhat.com>
We simply terminate qemu instead of issuing a reset as the semantics of
the setting dictate.
Fix it by handling it identically to 'fake reboot'.
We need to forbid the combination of 'onReboot' -> 'destroy' and
'onPoweroff' -> reboot though as the handling would be hairy and it
honetly makes no sense.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The qemu driver didn't ever implement any meaningful handling for the
'preserve' action.
Forbid the flag in the qemu def validator and update the documentation
to be factual.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
The qemu driver didn't ever implement any meaningful handling for the
'rename-restart' action.
At this point the following handling would take place:
'on_reboot' set to 'rename-restart' is ignored on guest-initiated
reboots, the guest simply reboots.
For on_poweroff set to 'rename-restart' the following happens:
guest initiated shutdown -> 'destroy'
libvirt initiated shutdown -> 'reboot'
In addition when 'on_reboot' is 'destroy' in addition to 'on_poweroff'
being 'rename-restart' the guest is able to execute instructions after
issuing a reset before libvirt terminates it. This will be addressed
separately later.
Forbid the flag in the qemu def validator and update the documentation
to be factual.
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
