When using command line passthrough users will often trip up over the
security protections like SELinux, DAC, namespaces, etc which will
deny access to files they are passing. This document explains the
various protections and how to deal with their policy, and/or how
to disable them.
Reviewed-by: NKashyap Chamarthy <kchamart@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

While we have CI testing coverage for many platforms, we don't test any
non-glibc based Linux and there are other non-Linux platforms we don't
officially target, both of which might hit regressions.
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

The table of contents in the RST based files uses <p> tags inside the
<li>, which results in 1em's worth of spacing above & below each
entry. This results in way too much whitespace in the ToC.
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

The current documentation is fairly terse and not easy to decode
for someone who's not intimately familiar with the inner workings
of timer devices. Expand on it by providing a somewhat verbose
description of what behavior each policy will result in, as seen
from both the guest OS and host point of view.

This is lifted directly from QEMU commit

  commit 2a7d957596786404c4ed16b089273de95a9580ad
  Author: Andrea Bolognani <abologna@redhat.com>
  Date:   Tue Feb 11 19:37:44 2020 +0100

    qapi: Expand documentation for LostTickPolicy

  v4.2.0-1442-g2a7d957596

The original text also matched word for word the documentation
found in QEMU.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NMichal Privoznik <mprivozn@redhat.com>

Signed-off-by: NLaine Stump <laine@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

This is a very simple thing to parse and format, but needs to be done
in 4 places, so two trivial utility functions have been made that can
be called from all the higher level parser/formatters:

  <domain><interface>
  <domain><interface><actual> (only in domain status)
  <network>
  <networkport>
Signed-off-by: NLaine Stump <laine@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

This is in the data structure and the parse/format functions, and is
getting passed all around correctly, it just was omitted from the RNG,
which hasn't been noticed because no human is creating <networkport>
XML, and so it's never getting validated against the schema.
Signed-off-by: NLaine Stump <laine@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NLaine Stump <laine@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Relevant code seems to treat forward modes 'route', 'nat', 'open' and 'none'
the same but documentation hasn't reflected that so far.
Signed-off-by: NPavel Mores <pmores@redhat.com>
Reviewed-by: NMichal Privoznik <mprivozn@redhat.com>

We are going to add support for specifying offset and size attributes
which will allow controling where the image and where the guest data
itself starts in the source of the disk. This will be represented by
a <slices> element filled with either a <slice type='storage'> for the
offset of the image format data.

Add the XML documentation and RNG schema.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

This new timer model will be used to control the behavior of the
virtual timer for KVM ARM/virt guests.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NMasayoshi Mizuma <m.mizuma@jp.fujitsu.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Users expect to be able to configure the <console> element and see
that configuration reflected into the <serial> element or at least
sticking, however due to our crazy back-compat code that doesn't
always happen.

There's really not much we can do to make this kind of corner cases
work as the user would expect, especially not without introducing
additional complexity in a part of libvirt that already has more
than a fair share of it; we can, however, improve the documentation
so that it will nudge said users in the right direction.

https://bugzilla.redhat.com/show_bug.cgi?id=1770725Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Simplify gathering the actual return value from a passed-through QMP
command when using 'qemu-monitor-command' by adding '--return-value'
switch which just extracts the 'return' section and alternatively
reports an error if the section is not present.

This simplifies gathering of some test data where the full reply would
need to be trimmed just for the actual return value.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NEric Blake <eblake@redhat.com>

Mention that we actually by default use QMP and clarify the rest
of the documentation.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NEric Blake <eblake@redhat.com>

This deletes all trace of gnulib from libvirt. We still
have the keycodemapdb submodule to deal with. The simple
solution taken was to update it when running autogen.sh.

Previously gnulib could auto-trigger refresh when running
'make' too. We could figure out a solution for this, but
with the pending meson rewrite it isn't worth worrying
about, given how infrequently keycodemapdb changes.
Reviewed-by: NPavel Hrdina <phrdina@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

When using ``....`` in RST, this results in <span class="literal">...</span>
instead of <code>...</code>. We thus need an extra rule to render it
with a monospace font. Colouring a light gray also helps the text
stand out a little more and matches background of <pre> blocks.
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

This patch adds support for the tpm-spapr device model for ppc64. The XML for
this type of TPM looks as follows:

 <tpm model='tpm-spapr'>
   <backend type='emulator'/>
 </tpm>

Extend the documentation.
Signed-off-by: NStefan Berger <stefanb@linux.vnet.ibm.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

The flag for the virDomainUndefine API is supported even if we report
that <backup supported='no'/>. Mention it in the docs.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NPavel Hrdina <phrdina@redhat.com>

The location of virt-aa-helper shown in the docs is incorrect.
The helper binary is installed under libexec dir.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

s/axnd/and/
Signed-off-by: NJán Tomko <jtomko@redhat.com>
Fixes: f0f34056

This is updating the releases and resources links so they point now to
crates.io for the releases and docs.rs for the api ref.
Signed-off-by: NSahid Orentino Ferdjaoui <sahid.ferdjaoui@canonical.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>

Since

  commit 201156ec
  Author: Daniel P. Berrangé <berrange@redhat.com>
  Date:   Mon Dec 16 10:06:50 2019 +0000

    docs: add pages to support Go module package resolution

it's possible to use

  import "libvirt.org/libvirt-go"
  import "libvirt.org/libvirt-go-xml"

in Go programs, which will result in the Go packages being
fetched directly from libvirt.org instead of GitHub.

The godoc website offers the API documentation for the updated
imports, and that's where we should send users.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

We haven't ever made releases of the Go components, which makes
sense because that's just not how that specific ecosystem works.

For people who are looking to use libvirt from Go, the brief
introductory pages located at the same URLs used to import the
packages are a better entry point than an empty directory
listing, so let's send them there instead.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NLaine Stump <laine@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

The subelement <teaming> of <interface> devices is used to configure a
simple teaming association between two interfaces in a domain. Example:

  <interface type='bridge'>
    <source bridge='br0'/>
    <model type='virtio'/>
    <mac address='00:11:22:33:44:55'/>
    <alias name='ua-backup0'/>
    <teaming type='persistent'/>
  </interface>
  <interface type='hostdev'>
    <source>
      <address type='pci' bus='0x02' slot='0x10' function='0x4'/>
    </source>
    <mac address='00:11:22:33:44:55'/>
    <teaming type='transient' persistent='ua-backup0'/>
  </interface>

The interface with <teaming type='persistent'/> is assumed to always
be present, while the interface with type='transient' may be be
unplugged and later re-plugged; the persistent='blah' attribute (and
in the one currently available implementation, also the matching MAC
addresses) is what associates the two devices with each other. It is
up to the hypervisor and the guest network drivers to determine what
to do with this information.
Signed-off-by: NLaine Stump <laine@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

We currently note that the QEMU embedded driver is experimental
in the drvqemu.html file, but we should do the same in the
virt-qemu-run man page.
Reviewed-by: NErik Skultety <eskultet@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

The --strict arg forces the rst tools to abort with an error instead
of printing warnings to stderr, or the output document.
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

You can't have two links with the same text when using named
link references (a single "_"). If you need multiple links
with the same text you must use anonymous link references
(a double "_").

There are also some duplicate section headers causing the
same problem with duplicate link targets.
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

Discourage passing secrets as commandline arguments.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

Simplify human usage of secret-set-value by adding --interactive which
will read the value of the secret from the terminal.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

Allow using the contents of --file without base64 decoding.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

Print a warning if users pass in secrets as command line arguments and
mention it in the man page.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

The necessity to specify the secret value as command argument is
insecure. Allow reading the secret from a file.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

Users might want to get the raw value instead of dealing with base64
encoding. This might be useful for redirection to file and also for
simple human-readable secrets.
Signed-off-by: NPeter Krempa <pkrempa@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

A few new companies and individuals contributed to libvirt since
the last time the gitdm configuration was updated.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

Signed-off-by: NAndrea Bolognani <abologna@redhat.com>

Also one stray angle bracket.
Signed-off-by: NJán Tomko <jtomko@redhat.com>
Fixes: 068efae5
Fixes: 3e9076e7Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>