Release of libvirt-8.2.0

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>

.color_coded.in

@@ -1,38 +0,0 @@
--I@abs_top_builddir@
--I@abs_top_srcdir@
--I@abs_top_builddir@/include
--I@abs_top_srcdir@/include
--I@abs_top_builddir@/src
--I@abs_top_srcdir@/src
--I@abs_top_builddir@/src/access
--I@abs_top_srcdir@/src/access
--I@abs_top_builddir@/src/admin
--I@abs_top_srcdir@/src/admin
--I@abs_top_builddir@/src/bhyve
--I@abs_top_srcdir@/src/bhyve
--I@abs_top_builddir@/src/conf
--I@abs_top_srcdir@/src/conf
--I@abs_top_builddir@/src/libxl
--I@abs_top_srcdir@/src/libxl
--I@abs_top_builddir@/src/locking
--I@abs_top_srcdir@/src/locking
--I@abs_top_builddir@/src/logging
--I@abs_top_srcdir@/src/logging
--I@abs_top_builddir@/src/lxc
--I@abs_top_srcdir@/src/lxc
--I@abs_top_builddir@/src/qemu
--I@abs_top_srcdir@/src/qemu
--I@abs_top_builddir@/src/remote
--I@abs_top_srcdir@/src/remote
--I@abs_top_builddir@/src/rpc
--I@abs_top_srcdir@/src/rpc
--I@abs_top_builddir@/src/secret
--I@abs_top_srcdir@/src/secret
--I@abs_top_builddir@/src/security
--I@abs_top_srcdir@/src/security
--I@abs_top_builddir@/src/util
--I@abs_top_srcdir@/src/util
--I@abs_top_builddir@/src/vmx
--I@abs_top_srcdir@/src/vmx
--I@abs_top_builddir@/src/xenconfig
--I@abs_top_srcdir@/src/xenconfig

.gitattributes

@@ -0,0 +1,22 @@
+# Generic git stuff
+**/.gitattributes export-ignore
+**/.gitignore export-ignore
+/.gitmodules export-ignore
+/.mailmap export-ignore
+
+# Project-specific git stuff
+/.gitpublish export-ignore
+/docs/gitdm export-ignore
+/docs/gitdm/** export-ignore
+/gitdm.config export-ignore
+
+# Code hosting stuff
+/.github export-ignore
+/.github/** export-ignore
+/.gitlab export-ignore
+/.gitlab/** export-ignore
+
+# CI stuff
+/.gitlab-ci.yml export-ignore
+/ci export-ignore
+/ci/** export-ignore

.gitlab-ci.yml

@@ -4,6 +4,7 @@ variables:
 stages:
   - containers
   - builds
+  - integration_tests
   - sanity_checks
 
 .script_variables: &script_variables |
@@ -14,7 +15,9 @@ stages:
   export VIR_TEST_VERBOSE="1"
   export VIR_TEST_DEBUG="1"
 
-include: '/ci/gitlab.yml'
+include:
+  - '/ci/gitlab.yml'
+  - '/ci/integration.yml'
 
 .native_build_job:
   extends: .gitlab_native_build_job
@@ -30,7 +33,8 @@ include: '/ci/gitlab.yml'
     - meson dist -C build --no-tests
     - if test -x /usr/bin/rpmbuild && test "$RPM" != "skip";
       then
-        rpmbuild --nodeps -ta build/meson-dist/libvirt-*.tar.xz;
+        rpmbuild --clean --nodeps --define "_topdir $PWD/rpmbuild/" -ta build/meson-dist/libvirt-*.tar.xz;
+        mv rpmbuild/RPMS/x86_64/ libvirt-rpms/;
       else
         meson compile -C build;
         meson test -C build --no-suite syntax-check --print-errorlogs;
@@ -56,9 +60,9 @@ include: '/ci/gitlab.yml'
 #    https://gitlab.com/libvirt/libvirt/-/jobs/artifacts/master/download?job=website
 website:
   stage: builds
-  image: $CI_REGISTRY_IMAGE/ci-centos-8:latest
+  image: $CI_REGISTRY_IMAGE/ci-almalinux-8:latest
   needs:
-    - x86_64-centos-8-container
+    - x86_64-almalinux-8-container
   before_script:
     - *script_variables
   script:
@@ -92,9 +96,9 @@ codestyle:
 #    https://gitlab.com/libvirt/libvirt/-/jobs/artifacts/master/download?job=potfile
 potfile:
   stage: builds
-  image: $CI_REGISTRY_IMAGE/ci-centos-8:latest
+  image: $CI_REGISTRY_IMAGE/ci-almalinux-8:latest
   needs:
-    - x86_64-centos-8-container
+    - x86_64-almalinux-8-container
   rules:
     - if: "$CI_COMMIT_BRANCH == 'master'"
   before_script:
@@ -114,9 +118,9 @@ potfile:
 
 # Coverity job that is run only by schedules
 coverity:
-  image: $CI_REGISTRY_IMAGE/ci-centos-8:latest
+  image: $CI_REGISTRY_IMAGE/ci-almalinux-8:latest
   needs:
-    - x86_64-centos-8-container
+    - x86_64-almalinux-8-container
   stage: builds
   script:
     - curl https://scan.coverity.com/download/linux64 --form project=$COVERITY_SCAN_PROJECT_NAME --form token=$COVERITY_SCAN_TOKEN -o /tmp/cov-analysis-linux64.tgz

.ycm_extra_conf.py.in

@@ -1,43 +0,0 @@
-flags = [
-  '-I@abs_top_builddir@',
-  '-I@abs_top_srcdir@',
-  '-I@abs_top_builddir@/include',
-  '-I@abs_top_srcdir@/include',
-  '-I@abs_top_builddir@/src',
-  '-I@abs_top_srcdir@/src',
-  '-I@abs_top_builddir@/src/access',
-  '-I@abs_top_srcdir@/src/access',
-  '-I@abs_top_builddir@/src/admin',
-  '-I@abs_top_srcdir@/src/admin',
-  '-I@abs_top_builddir@/src/bhyve',
-  '-I@abs_top_srcdir@/src/bhyve',
-  '-I@abs_top_builddir@/src/conf',
-  '-I@abs_top_srcdir@/src/conf',
-  '-I@abs_top_builddir@/src/libxl',
-  '-I@abs_top_srcdir@/src/libxl',
-  '-I@abs_top_builddir@/src/locking',
-  '-I@abs_top_srcdir@/src/locking',
-  '-I@abs_top_builddir@/src/logging',
-  '-I@abs_top_srcdir@/src/logging',
-  '-I@abs_top_builddir@/src/lxc',
-  '-I@abs_top_srcdir@/src/lxc',
-  '-I@abs_top_builddir@/src/qemu',
-  '-I@abs_top_srcdir@/src/qemu',
-  '-I@abs_top_builddir@/src/remote',
-  '-I@abs_top_srcdir@/src/remote',
-  '-I@abs_top_builddir@/src/rpc',
-  '-I@abs_top_srcdir@/src/rpc',
-  '-I@abs_top_builddir@/src/secret',
-  '-I@abs_top_srcdir@/src/secret',
-  '-I@abs_top_builddir@/src/security',
-  '-I@abs_top_srcdir@/src/security',
-  '-I@abs_top_builddir@/src/util',
-  '-I@abs_top_srcdir@/src/util',
-  '-I@abs_top_builddir@/src/vmx',
-  '-I@abs_top_srcdir@/src/vmx',
-  '-I@abs_top_builddir@/src/xenconfig',
-  '-I@abs_top_srcdir@/src/xenconfig',
-]
-
-def FlagsForFile(filename, **kwargs):
-  return { 'flags': flags, 'do_cache': True }

NEWS.rst

@@ -8,6 +8,166 @@ the changes introduced by each of them.
 For a more fine-grained view, use the `git log`_.
 
 
+v8.2.0 (2022-04-01)
+===================
+
+* **New features**
+
+  * qemu: Introduce ``manual`` disk snapshot mode
+
+    This new mode allows users to synchronize libvirt snapshots with snapshots
+    which need to be done outside of libvirt e.g. when 'vhost-user-blk' is used
+    to back the disk.
+
+  * Introduce memory allocation threads
+
+    When starting a QEMU guest, libvirt can now instruct QEMU to allocate
+    guest's memory in parallel. This may be handy when guest has large amounts
+    of memory.
+
+* **Improvements**
+
+  * qemu: ``VIR_MIGRATE_PARAM_TLS_DESTINATION`` now works with non-shared storage migration
+
+    The setting now also applies to the NBD connections for non-shared storage
+    migration allowing migration to proceed even when the user expects certificate
+    name not to match.
+
+  * qemu: Allow overrides of device properties via the qemu namespace
+
+    Users wishing to override or modify properties of devices configured by
+    libvirt can use the ``<qemu:deviceOverride>`` QEMU namespace element to
+    specify the overrides instead of relying on the argv passthrough of the
+    ``-set`` qemu commandline option which no longer works with new qemu.
+
+  * qemu: Allow passing file descriptors to ``virsh qemu-monitor-command``
+
+    Passing FDs allows users wanting to experiment with qemu driven by libvirt
+    use commands like ``add-fd`` properly.
+
+  * libxl: Turn on user aliases
+
+    Users can now use so called user aliases for XEN domains.
+
+  * Implement support for FUSE3
+
+    The LXC driver uses fuse to overwrite some lines in ``/proc/meminfo``
+    inside containers so that they see correct amount of memory given to them.
+    The code was changed so that both ``fuse`` and ``fuse3`` are supported.
+
+  * Improve domain save/restore throughput
+
+    Code that's handling save or restore of QEMU domains was changed resulting
+    in better performance of I/O and thus shortening time needed for the operation.
+
+* **Bug fixes**
+
+  * Both build and tests should now pass on Alpine Linux or any other
+    distribution with musl libc.
+
+  * virsh: Fix integer overflow in allocpages
+
+    On hosts which support hugepages larger than 1GiB ``virsh allocpages``
+    failed to accept them because of an integer overflow. This is now fixed.
+
+  * qemu: Fix segmentation fault in virDomainUndefineFlags
+
+    When a domain without any ``<loader/>`` was being undefined, libvirt has
+    crashed. This is now fixed.
+
+  * lxc: Fix unaligned reads of /proc/meminfo within a container
+
+    When /proc/meminfo was read in chunks smaller than the entire file, libvirt
+    would produce mangled output. While porting the code to FUSE3 this area was
+    reworked and the file can now be read with any granularity.
+
+  * qemu: Be less aggressive around cgroup_device_acl
+
+    A basic set of devices common to every domain can be set in ``qemu.conf``
+    via cgroup_device_acl knob. Devices from this set are allowed in CGroup and
+    created in domain private namespace for every domain. However, upon device
+    hotunplug it may have had happened that libvirt mistakenly denied a device
+    from this set and/or removed it from the namespace. For instance,
+    /dev/urandom was removed and denied in CGroup on RNG hotunplug.
+
+  * nodedev: trigger mdev device definition update on udev add and remove
+
+    When nodedev objects are added and removed mdev device definitions are
+    updated to report correct associated parent.
+
+
+v8.1.0 (2022-03-01)
+===================
+
+* **New features**
+
+  * qemu: Add hvf domain type for Hypervisor.framework
+
+    It works on Intel machines as well as recent machines powered by Apple
+    Silicon. QEMU 6.2.0 is needed for Apple Silicon support.
+
+  * qemu: Support mode option for dirtyrate calculation
+
+    Introduce ``virDomainDirtyRateCalcFlags`` as parameter of
+    ``virDomainStartDirtyRateCalc``, which is used to specify the mode of
+    dirty page rate calculation.
+
+    Add ``--mode`` option to ``virsh domdirtyrate-calc``, which can be
+    either of the following 3 options:
+    ``page-sampling, dirty-bitmap, dirty-ring``.
+
+    Add ``calc_mode`` field for dirtyrate statistics returned by
+    ``virsh domstats --dirtyrate``, also add ``vCPU dirtyrate`` if
+    ``dirty-ring`` mode was used in last measurement.
+
+* **Improvements**
+
+  * packaging: sysconfig files no longer installed
+
+    libvirt used to provide defaults in various /etc/sysconfig/ files, such
+    as /etc/sysconfig/libvirtd. Since these files are owned by the admin, this
+    made it difficult to change built-in defaults in case such file was
+    modified by the admin. The built-in defaults are now part of the provided
+    systemd unit files, such as libvirtd.service. These unit files continue
+    to parse sysconfig files, in case they are created by the admin and filled
+    with the desired key=value pairs.
+
+  * virnetdev: Ignore EPERM on implicit clearing of VF VLAN ID
+
+    Libvirt will now ignore EPERM errors on attempts to implicitly clear a
+    VLAN ID (when a VLAN is not explicitly provided via an interface XML
+    using a 0 or a non-zero value) as SmartNIC DPUs do not expose VLAN
+    programming capabilities to the hypervisor host. This allows Libvirt
+    clients to avoid specifying a VLAN and expect VF configuration to work
+    since Libvirt tries to clear a VLAN in the same operation
+    as setting a MAC address for VIR_DOMAIN_NET_TYPE_HOSTDEV devices which
+    is now split into two distinct operations. EPERM errors received while
+    trying to program a non-zero VLAN ID or explicitly program a VLAN ID 0
+    will still cause errors as before so there is no change in behavior
+    in those cases.
+
+* **Bug fixes**
+
+  * Remove unix sockets from filesystem when disabling a '.socket' systemd unit
+
+    The presence of the socket files is used by our remote driver to determine
+    which service to access. Since neither systemd nor the daemons clean up the
+    socket file clients were running into problems when a modular deployment was
+    switched to monolithic ``libvirtd``.
+
+  * qemu: Fixes of fd passing during hotplug and hotunplug of chardevs
+
+    FDs used as chardev backing are now properly removed when hot-unplugging
+    a chardev from qemu and hotplugged chardevs now properly use ``virtlogd``
+    to handle the input and output from qemu.
+
+  * RPM: Run pre/post-install steps on ``daemon-driver-storage-core``
+
+    Previously the pre/post-install code was part of the meta-package which
+    installed all storage driver sub-packages thus a minimalistic install
+    of the storage driver didn't behave correctly.
+
+
 v8.0.0 (2022-01-14)
 ===================
 

build-aux/meson.build

@@ -20,7 +20,7 @@ endif
 
 if host_machine.system() == 'freebsd'
   grep_prog = find_program('grep')
-  grep_cmd = run_command(grep_prog, '--version')
+  grep_cmd = run_command(grep_prog, '--version', check: true)
   if grep_cmd.stdout().startswith('grep (BSD grep')
     grep_prog = find_program('/usr/local/bin/grep', required: false)
     if not grep_prog.found()

build-aux/syntax-check.mk

@@ -116,6 +116,7 @@ VC_LIST_ALWAYS_EXCLUDE_REGEX = \
 # the safewrite wrapper.
 sc_avoid_write:
 	@prohibit='\<write *\(' \
+	exclude='sc_avoid_write' \
 	in_vc_files='\.c$$' \
 	halt='consider using safewrite instead of write' \
 	  $(_sc_search_regexp)
@@ -244,7 +245,7 @@ sc_prohobit_vsnprintf:
 
 sc_prohibit_strdup:
 	@prohibit='\<strn?dup\> *\(' \
-	halt='use VIR_STRDUP, not strdup' \
+	halt='use g_str(n)dup, not str(n)dup' \
 	  $(_sc_search_regexp)
 
 # Prefer virSetUIDGID.
@@ -874,20 +875,61 @@ sc_prohibit_obj_free_apis_in_virsh:
 	halt='avoid using public virXXXFree in virsh, use virsh-prefixed wrappers instead' \
 	  $(_sc_search_regexp)
 
-https_sites = www.libvirt.org
+# Links in various schemas
-https_sites += libvirt.org
+http_sites = libvirt.org.*\/schemas\/
-https_sites += security.libvirt.org
+http_sites += \.dtd
-https_sites += qemu.org
+http_sites += libosinfo
-https_sites += www.qemu.org
+http_sites += localhost
-https_sites += wiki.qemu.org
+http_sites += rdf:resource
-https_sites += linux-kvm.org
+http_sites += schemas.dmtf.org
-https_sites += www.linux-kvm.org
+http_sites += schemas.microsoft.com
+http_sites += schemas.xmlsoap.org
+http_sites += www.inkscape.org
+http_sites += www.innotek.de
+http_sites += www.w3.org
+http_sites += xmlns
 
-https_re= ($(subst $(space),|,$(https_sites)))
+# Links in licenses
+http_sites += scripts.sil.org
+http_sites += www.gnu.org\/licenses\/
+http_sites += www.sun.com
+
+# Example links
+http_sites += example.com
+http_sites += example.org
+http_sites += herp.derp
+
+# HTTP-only sites
+http_sites += 0pointer.de
+http_sites += mah.everybody.org
+http_sites += mingw.org
+http_sites += munin.projects.linpro.no
+http_sites += netcat.sourceforge.net
+http_sites += snooze.inria.fr
+http_sites += www.nimbusproject.org
+http_sites += www.odin.com
+http_sites += www.sflow.net
+http_sites += xmlsoft.org
+http_sites += etallen.com
+
+# dead sites
+http_sites += blog.lystor.org.ua
+http_sites += blog.mes-stats.fr
+http_sites += cc1.ifj.edu.pl
+http_sites += www.javvin.com
+
+# 404 links
+http_sites += publib.boulder.ibm.com
+http_sites += kerneltrap.org
+http_sites += www.microsoft.com
+http_sites += xenbits.xen.org
+http_sites += lovezutto.googlepages.com
+
+http_re= ($(subst $(space),|,$(http_sites)))
 
 sc_prohibit_http_urls:
-	@prohibit='http://$(https_re)' \
+	@prohibit='http://\w' \
-	exclude="/schemas/" \
+	exclude="$(http_re)" \
 	halt='Links must use https:// protocol' \
 	  $(_sc_search_regexp)
 
@@ -1506,7 +1548,7 @@ sc_spacing-check:
 	  { echo '$(ME): incorrect formatting' 1>&2; exit 1; }
 
 sc_mock-noinline:
-	$(AM_V_GEN)$(VC_LIST_EXCEPT) | $(GREP) '\.[ch]$$' | $(RUNUTF8) xargs \
+	$(AM_V_GEN)$(VC_LIST_EXCEPT) | $(GREP) '\.[ch]$$' | $(RUNUTF8) \
 	$(PYTHON) $(top_srcdir)/scripts/mock-noinline.py
 
 sc_header-ifdef:
@@ -1527,10 +1569,7 @@ sc_prohibit_enum_impl_with_vir_prefix_in_virsh:
 # List all syntax-check exemptions:
 exclude_file_name_regexp--sc_avoid_strcase = ^tools/vsh\.h$$
 
-_src1=libvirt-stream|qemu/qemu_monitor|util/vir(command|file|fdstream)|rpc/virnetsocket|lxc/lxc_controller|locking/lock_daemon|logging/log_daemon|remote/remote_ssh_helper
+exclude_file_name_regexp--sc_avoid_write = ^src/libvirt-stream\.c$$
-_test1=shunloadtest|virnettlscontexttest|virnettlssessiontest|vircgroupmock|commandhelper
-exclude_file_name_regexp--sc_avoid_write = \
-  ^(src/($(_src1))|tools/virsh-console|tests/($(_test1)))\.c$$
 
 exclude_file_name_regexp--sc_bindtextdomain = .*
 
@@ -1580,7 +1619,7 @@ exclude_file_name_regexp--sc_prohibit_newline_at_end_of_diagnostic = \
   ^src/rpc/gendispatch\.pl$$
 
 exclude_file_name_regexp--sc_prohibit_nonreentrant = \
-  ^((po|tests|examples)/|docs/.*(py|js|html\.in)|run.in$$|tools/wireshark/util/genxdrstub\.pl|tools/virt-login-shell\.c$$)
+  ^((po|tests|examples)/|docs/.*(py|js|html\.in|.rst)|run.in$$|tools/wireshark/util/genxdrstub\.pl|tools/virt-login-shell\.c$$)
 
 exclude_file_name_regexp--sc_prohibit_select = \
 	^build-aux/syntax-check\.mk$$

ci/containers/almalinux-8.Dockerfile

@@ -4,7 +4,7 @@
 #
 # https://gitlab.com/libvirt/libvirt-ci
 
-FROM docker.io/library/centos:8
+FROM docker.io/library/almalinux:8
 
 RUN dnf update -y && \
     dnf install 'dnf-command(config-manager)' -y && \

ci/containers/alpine-314.Dockerfile

@@ -0,0 +1,82 @@
+# THIS FILE WAS AUTO-GENERATED
+#
+#  $ lcitool manifest ci/manifest.yml
+#
+# https://gitlab.com/libvirt/libvirt-ci
+
+FROM docker.io/library/alpine:3.14
+
+RUN apk update && \
+    apk upgrade && \
+    apk add \
+        acl-dev \
+        attr-dev \
+        audit-dev \
+        augeas \
+        bash-completion \
+        ca-certificates \
+        ccache \
+        ceph-dev \
+        clang \
+        curl-dev \
+        cyrus-sasl-dev \
+        diffutils \
+        dnsmasq \
+        eudev-dev \
+        fuse-dev \
+        gcc \
+        gettext \
+        git \
+        glib-dev \
+        gnutls-dev \
+        grep \
+        iproute2 \
+        iptables \
+        kmod \
+        libcap-ng-dev \
+        libnl3-dev \
+        libpcap-dev \
+        libpciaccess-dev \
+        libselinux-dev \
+        libssh-dev \
+        libssh2-dev \
+        libtirpc-dev \
+        libxml2-dev \
+        libxml2-utils \
+        libxslt \
+        lvm2 \
+        lvm2-dev \
+        make \
+        meson \
+        musl-dev \
+        netcf-dev \
+        nfs-utils \
+        numactl-dev \
+        open-iscsi \
+        parted-dev \
+        perl \
+        pkgconf \
+        polkit \
+        py3-docutils \
+        py3-flake8 \
+        python3 \
+        qemu-img \
+        readline-dev \
+        rpcgen \
+        samurai \
+        sed \
+        util-linux-dev \
+        wireshark-dev \
+        xen-dev \
+        yajl-dev && \
+    apk list | sort > /packages.txt && \
+    mkdir -p /usr/libexec/ccache-wrappers && \
+    ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/cc && \
+    ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/clang && \
+    ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/gcc
+
+ENV LANG "en_US.UTF-8"
+ENV MAKE "/usr/bin/make"
+ENV NINJA "/usr/bin/ninja"
+ENV PYTHON "/usr/bin/python3"
+ENV CCACHE_WRAPPERSDIR "/usr/libexec/ccache-wrappers"

ci/containers/alpine-edge.Dockerfile

@@ -0,0 +1,81 @@
+# THIS FILE WAS AUTO-GENERATED
+#
+#  $ lcitool manifest ci/manifest.yml
+#
+# https://gitlab.com/libvirt/libvirt-ci
+
+FROM docker.io/library/alpine:edge
+
+RUN apk update && \
+    apk upgrade && \
+    apk add \
+        acl-dev \
+        attr-dev \
+        audit-dev \
+        augeas \
+        bash-completion \
+        ca-certificates \
+        ccache \
+        ceph-dev \
+        clang \
+        curl-dev \
+        cyrus-sasl-dev \
+        diffutils \
+        dnsmasq \
+        eudev-dev \
+        fuse-dev \
+        gcc \
+        gettext \
+        git \
+        glib-dev \
+        gnutls-dev \
+        grep \
+        iproute2 \
+        iptables \
+        kmod \
+        libcap-ng-dev \
+        libnl3-dev \
+        libpcap-dev \
+        libpciaccess-dev \
+        libselinux-dev \
+        libssh-dev \
+        libssh2-dev \
+        libtirpc-dev \
+        libxml2-dev \
+        libxml2-utils \
+        libxslt \
+        lvm2 \
+        lvm2-dev \
+        make \
+        meson \
+        musl-dev \
+        netcf-dev \
+        nfs-utils \
+        numactl-dev \
+        open-iscsi \
+        parted-dev \
+        perl \
+        pkgconf \
+        polkit \
+        py3-docutils \
+        py3-flake8 \
+        python3 \
+        qemu-img \
+        readline-dev \
+        samurai \
+        sed \
+        util-linux-dev \
+        wireshark-dev \
+        xen-dev \
+        yajl-dev && \
+    apk list | sort > /packages.txt && \
+    mkdir -p /usr/libexec/ccache-wrappers && \
+    ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/cc && \
+    ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/clang && \
+    ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/gcc
+
+ENV LANG "en_US.UTF-8"
+ENV MAKE "/usr/bin/make"
+ENV NINJA "/usr/bin/ninja"
+ENV PYTHON "/usr/bin/python3"
+ENV CCACHE_WRAPPERSDIR "/usr/libexec/ccache-wrappers"

ci/containers/centos-stream-9.Dockerfile

@@ -0,0 +1,90 @@
+# THIS FILE WAS AUTO-GENERATED
+#
+#  $ lcitool manifest ci/manifest.yml
+#
+# https://gitlab.com/libvirt/libvirt-ci
+
+FROM quay.io/centos/centos:stream9
+
+RUN dnf update -y && \
+    dnf install 'dnf-command(config-manager)' -y && \
+    dnf config-manager --set-enabled -y crb && \
+    dnf install -y \
+        https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm \
+        https://dl.fedoraproject.org/pub/epel/epel-next-release-latest-9.noarch.rpm && \
+    dnf install -y \
+        audit-libs-devel \
+        augeas \
+        bash-completion \
+        ca-certificates \
+        clang \
+        cpp \
+        cyrus-sasl-devel \
+        device-mapper-devel \
+        diffutils \
+        dnsmasq \
+        dwarves \
+        ebtables \
+        firewalld-filesystem \
+        fuse-devel \
+        gcc \
+        gettext \
+        git \
+        glib2-devel \
+        glibc-devel \
+        glibc-langpack-en \
+        gnutls-devel \
+        grep \
+        iproute \
+        iproute-tc \
+        iptables \
+        iscsi-initiator-utils \
+        kmod \
+        libacl-devel \
+        libattr-devel \
+        libblkid-devel \
+        libcap-ng-devel \
+        libcurl-devel \
+        libnl3-devel \
+        libpcap-devel \
+        libpciaccess-devel \
+        librbd-devel \
+        libselinux-devel \
+        libssh-devel \
+        libtirpc-devel \
+        libwsman-devel \
+        libxml2 \
+        libxml2-devel \
+        libxslt \
+        lvm2 \
+        make \
+        meson \
+        nfs-utils \
+        ninja-build \
+        numactl-devel \
+        numad \
+        parted-devel \
+        perl-base \
+        pkgconfig \
+        polkit \
+        python3 \
+        python3-docutils \
+        qemu-img \
+        readline-devel \
+        rpcgen \
+        rpm-build \
+        sanlock-devel \
+        scrub \
+        sed \
+        systemd-devel \
+        systemtap-sdt-devel \
+        wireshark-devel \
+        yajl-devel && \
+    dnf autoremove -y && \
+    dnf clean all -y && \
+    rpm -qa | sort > /packages.txt
+
+ENV LANG "en_US.UTF-8"
+ENV MAKE "/usr/bin/make"
+ENV NINJA "/usr/bin/ninja"
+ENV PYTHON "/usr/bin/python3"

ci/containers/debian-10-cross-aarch64.Dockerfile

@@ -55,8 +55,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     sed -Ei 's,^# (en_US\.UTF-8 .*)$,\1,' /etc/locale.gen && \
     dpkg-reconfigure locales
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/debian-10-cross-armv6l.Dockerfile

@@ -55,8 +55,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     sed -Ei 's,^# (en_US\.UTF-8 .*)$,\1,' /etc/locale.gen && \
     dpkg-reconfigure locales
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/debian-10-cross-armv7l.Dockerfile

@@ -55,8 +55,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     sed -Ei 's,^# (en_US\.UTF-8 .*)$,\1,' /etc/locale.gen && \
     dpkg-reconfigure locales
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/debian-10-cross-i686.Dockerfile

@@ -55,8 +55,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     sed -Ei 's,^# (en_US\.UTF-8 .*)$,\1,' /etc/locale.gen && \
     dpkg-reconfigure locales
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/debian-10-cross-mips.Dockerfile

@@ -55,8 +55,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     sed -Ei 's,^# (en_US\.UTF-8 .*)$,\1,' /etc/locale.gen && \
     dpkg-reconfigure locales
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/debian-10-cross-mips64el.Dockerfile

@@ -55,8 +55,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     sed -Ei 's,^# (en_US\.UTF-8 .*)$,\1,' /etc/locale.gen && \
     dpkg-reconfigure locales
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/debian-10-cross-mipsel.Dockerfile

@@ -55,8 +55,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     sed -Ei 's,^# (en_US\.UTF-8 .*)$,\1,' /etc/locale.gen && \
     dpkg-reconfigure locales
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/debian-10-cross-ppc64le.Dockerfile

@@ -55,8 +55,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     sed -Ei 's,^# (en_US\.UTF-8 .*)$,\1,' /etc/locale.gen && \
     dpkg-reconfigure locales
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/debian-10-cross-s390x.Dockerfile

@@ -55,8 +55,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     sed -Ei 's,^# (en_US\.UTF-8 .*)$,\1,' /etc/locale.gen && \
     dpkg-reconfigure locales
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/debian-10.Dockerfile

@@ -97,8 +97,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/clang && \
     ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/gcc
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/opensuse-leap-152.Dockerfile

@@ -92,8 +92,7 @@ RUN zypper update -y && \
     ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/clang && \
     ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/gcc
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/ubuntu-1804.Dockerfile

@@ -99,8 +99,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/clang && \
     ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/gcc
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/containers/ubuntu-2004.Dockerfile

@@ -98,8 +98,7 @@ RUN export DEBIAN_FRONTEND=noninteractive && \
     ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/clang && \
     ln -s /usr/bin/ccache /usr/libexec/ccache-wrappers/gcc
 
-RUN pip3 install \
+RUN pip3 install meson==0.56.0
-         meson==0.56.0
 
 ENV LANG "en_US.UTF-8"
 ENV MAKE "/usr/bin/make"

ci/gitlab.yml

@@ -10,8 +10,7 @@
   stage: containers
   needs: []
   services:
-    - name: registry.gitlab.com/libvirt/libvirt-ci/docker-dind:master
+    - docker:dind
-      alias: docker
   before_script:
     - export TAG="$CI_REGISTRY_IMAGE/ci-$NAME:latest"
     - export COMMON_TAG="$CI_REGISTRY/libvirt/libvirt/ci-$NAME:latest"
@@ -80,11 +79,25 @@ check-dco:
 
 # Native container jobs
 
-x86_64-centos-8-container:
+x86_64-almalinux-8-container:
   extends: .container_job
   allow_failure: false
   variables:
-    NAME: centos-8
+    NAME: almalinux-8
+
+
+x86_64-alpine-314-container:
+  extends: .container_job
+  allow_failure: false
+  variables:
+    NAME: alpine-314
+
+
+x86_64-alpine-edge-container:
+  extends: .container_job
+  allow_failure: true
+  variables:
+    NAME: alpine-edge
 
 
 x86_64-centos-stream-8-container:
@@ -94,6 +107,13 @@ x86_64-centos-stream-8-container:
     NAME: centos-stream-8
 
 
+x86_64-centos-stream-9-container:
+  extends: .container_job
+  allow_failure: false
+  variables:
+    NAME: centos-stream-9
+
+
 x86_64-debian-10-container:
   extends: .container_job
   allow_failure: false
@@ -372,25 +392,43 @@ mingw64-fedora-rawhide-container:
 
 # Native build jobs
 
-x86_64-centos-8:
+x86_64-almalinux-8:
   extends: .native_build_job
   needs:
-    - x86_64-centos-8-container
+    - x86_64-almalinux-8-container
   allow_failure: false
   variables:
-    NAME: centos-8
+    NAME: almalinux-8
     RPM: skip
 
 
-x86_64-centos-8-clang:
+x86_64-almalinux-8-clang:
   extends: .native_build_job
   needs:
-    - x86_64-centos-8-container
+    - x86_64-almalinux-8-container
   allow_failure: false
   variables:
-    NAME: centos-8
-    RPM: skip
     CC: clang
+    NAME: almalinux-8
+    RPM: skip
+
+
+x86_64-alpine-314:
+  extends: .native_build_job
+  needs:
+    - x86_64-alpine-314-container
+  allow_failure: false
+  variables:
+    NAME: alpine-314
+
+
+x86_64-alpine-edge:
+  extends: .native_build_job
+  needs:
+    - x86_64-alpine-edge-container
+  allow_failure: true
+  variables:
+    NAME: alpine-edge
 
 
 x86_64-centos-stream-8:
@@ -400,7 +438,23 @@ x86_64-centos-stream-8:
   allow_failure: false
   variables:
     NAME: centos-stream-8
-    RPM: skip
+  artifacts:
+    expire_in: 1 day
+    paths:
+      - libvirt-rpms
+
+
+x86_64-centos-stream-9:
+  extends: .native_build_job
+  needs:
+    - x86_64-centos-stream-9-container
+  allow_failure: false
+  variables:
+    NAME: centos-stream-9
+  artifacts:
+    expire_in: 1 day
+    paths:
+      - libvirt-rpms
 
 
 x86_64-debian-10:
@@ -446,6 +500,10 @@ x86_64-fedora-34:
   allow_failure: false
   variables:
     NAME: fedora-34
+  artifacts:
+    expire_in: 1 day
+    paths:
+      - libvirt-rpms
 
 
 x86_64-fedora-35:
@@ -455,6 +513,10 @@ x86_64-fedora-35:
   allow_failure: false
   variables:
     NAME: fedora-35
+  artifacts:
+    expire_in: 1 day
+    paths:
+      - libvirt-rpms
 
 
 x86_64-fedora-rawhide:
@@ -472,8 +534,8 @@ x86_64-fedora-rawhide-clang:
     - x86_64-fedora-rawhide-container
   allow_failure: true
   variables:
-    NAME: fedora-rawhide
     CC: clang
+    NAME: fedora-rawhide
     RPM: skip
 
 
@@ -512,9 +574,9 @@ x86_64-ubuntu-2004:
     - x86_64-ubuntu-2004-container
   allow_failure: false
   variables:
-    NAME: ubuntu-2004
     ASAN_OPTIONS: verify_asan_link_order=0
     MESON_ARGS: -Db_lundef=false -Db_sanitize=address,undefined
+    NAME: ubuntu-2004
     UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
 
 
@@ -524,9 +586,9 @@ x86_64-ubuntu-2004-clang:
     - x86_64-ubuntu-2004-container
   allow_failure: false
   variables:
-    NAME: ubuntu-2004
     CC: clang
     MESON_ARGS: -Db_lundef=false -Db_sanitize=address,undefined
+    NAME: ubuntu-2004
     UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
 
 
@@ -539,8 +601,8 @@ armv6l-debian-10:
     - armv6l-debian-10-container
   allow_failure: false
   variables:
-    NAME: debian-10
     CROSS: armv6l
+    NAME: debian-10
 
 
 mips-debian-10:
@@ -549,8 +611,8 @@ mips-debian-10:
     - mips-debian-10-container
   allow_failure: false
   variables:
-    NAME: debian-10
     CROSS: mips
+    NAME: debian-10
 
 
 mipsel-debian-10:
@@ -559,8 +621,8 @@ mipsel-debian-10:
     - mipsel-debian-10-container
   allow_failure: false
   variables:
-    NAME: debian-10
     CROSS: mipsel
+    NAME: debian-10
 
 
 armv7l-debian-11:
@@ -569,8 +631,8 @@ armv7l-debian-11:
     - armv7l-debian-11-container
   allow_failure: false
   variables:
-    NAME: debian-11
     CROSS: armv7l
+    NAME: debian-11
 
 
 mips64el-debian-11:
@@ -579,8 +641,8 @@ mips64el-debian-11:
     - mips64el-debian-11-container
   allow_failure: false
   variables:
-    NAME: debian-11
     CROSS: mips64el
+    NAME: debian-11
 
 
 ppc64le-debian-11:
@@ -589,8 +651,8 @@ ppc64le-debian-11:
     - ppc64le-debian-11-container
   allow_failure: false
   variables:
-    NAME: debian-11
     CROSS: ppc64le
+    NAME: debian-11
 
 
 aarch64-debian-sid:
@@ -599,8 +661,8 @@ aarch64-debian-sid:
     - aarch64-debian-sid-container
   allow_failure: true
   variables:
-    NAME: debian-sid
     CROSS: aarch64
+    NAME: debian-sid
 
 
 i686-debian-sid:
@@ -609,8 +671,8 @@ i686-debian-sid:
     - i686-debian-sid-container
   allow_failure: true
   variables:
-    NAME: debian-sid
     CROSS: i686
+    NAME: debian-sid
 
 
 s390x-debian-sid:
@@ -619,8 +681,8 @@ s390x-debian-sid:
     - s390x-debian-sid-container
   allow_failure: true
   variables:
-    NAME: debian-sid
     CROSS: s390x
+    NAME: debian-sid
 
 
 mingw64-fedora-35:
@@ -629,8 +691,8 @@ mingw64-fedora-35:
     - mingw64-fedora-35-container
   allow_failure: false
   variables:
-    NAME: fedora-35
     CROSS: mingw64
+    NAME: fedora-35
 
 
 mingw32-fedora-rawhide:
@@ -639,8 +701,8 @@ mingw32-fedora-rawhide:
     - mingw32-fedora-rawhide-container
   allow_failure: true
   variables:
-    NAME: fedora-rawhide
     CROSS: mingw32
+    NAME: fedora-rawhide
 
 
 # Native cirrus build jobs
@@ -650,13 +712,13 @@ x86_64-freebsd-12:
   needs: []
   allow_failure: false
   variables:
-    NAME: freebsd-12
-    CIRRUS_VM_INSTANCE_TYPE: freebsd_instance
-    CIRRUS_VM_IMAGE_SELECTOR: image_family
     CIRRUS_VM_IMAGE_NAME: freebsd-12-2
+    CIRRUS_VM_IMAGE_SELECTOR: image_family
+    CIRRUS_VM_INSTANCE_TYPE: freebsd_instance
+    INSTALL_COMMAND: pkg install -y
+    NAME: freebsd-12
     UPDATE_COMMAND: pkg update
     UPGRADE_COMMAND: pkg upgrade -y
-    INSTALL_COMMAND: pkg install -y
 
 
 x86_64-freebsd-13:
@@ -664,13 +726,13 @@ x86_64-freebsd-13:
   needs: []
   allow_failure: false
   variables:
-    NAME: freebsd-13
-    CIRRUS_VM_INSTANCE_TYPE: freebsd_instance
-    CIRRUS_VM_IMAGE_SELECTOR: image_family
     CIRRUS_VM_IMAGE_NAME: freebsd-13-0
+    CIRRUS_VM_IMAGE_SELECTOR: image_family
+    CIRRUS_VM_INSTANCE_TYPE: freebsd_instance
+    INSTALL_COMMAND: pkg install -y
+    NAME: freebsd-13
     UPDATE_COMMAND: pkg update
     UPGRADE_COMMAND: pkg upgrade -y
-    INSTALL_COMMAND: pkg install -y
 
 
 x86_64-macos-11:
@@ -678,12 +740,12 @@ x86_64-macos-11:
   needs: []
   allow_failure: false
   variables:
-    NAME: macos-11
-    CIRRUS_VM_INSTANCE_TYPE: osx_instance
-    CIRRUS_VM_IMAGE_SELECTOR: image
     CIRRUS_VM_IMAGE_NAME: big-sur-base
-    UPDATE_COMMAND: brew update
+    CIRRUS_VM_IMAGE_SELECTOR: image
-    UPGRADE_COMMAND: brew upgrade
+    CIRRUS_VM_INSTANCE_TYPE: osx_instance
     INSTALL_COMMAND: brew install
+    NAME: macos-11
     PATH_EXTRA: /usr/local/opt/ccache/libexec:/usr/local/opt/gettext/bin:/usr/local/opt/libpcap/bin:/usr/local/opt/libxslt/bin:/usr/local/opt/rpcgen/bin
     PKG_CONFIG_PATH: /usr/local/opt/curl/lib/pkgconfig:/usr/local/opt/libpcap/lib/pkgconfig:/usr/local/opt/libxml2/lib/pkgconfig:/usr/local/opt/ncurses/lib/pkgconfig:/usr/local/opt/readline/lib/pkgconfig
+    UPDATE_COMMAND: brew update
+    UPGRADE_COMMAND: brew upgrade

ci/integration.yml

@@ -0,0 +1,116 @@
+.integration_tests:
+  stage: integration_tests
+  before_script:
+    - mkdir "$SCRATCH_DIR"
+    - sudo sh -c "echo DefaultLimitCORE=infinity >> /etc/systemd/system.conf" # Explicitly allow storing cores globally
+    - sudo systemctl daemon-reexec # need to reexec systemd after changing config
+    - sudo dnf install -y libvirt-rpms/* libvirt-perl-rpms/*
+    - sudo pip3 install --prefix=/usr avocado-framework
+    - source /etc/os-release  # in order to query the vendor-provided variables
+    - if test "$ID" = "centos" && test "$VERSION_ID" -lt 9 ||
+         test "$ID" = "fedora" && test "$VERSION_ID" -lt 35;
+      then
+        DAEMONS="libvirtd virtlogd virtlockd";
+      else
+        DAEMONS="virtproxyd virtqemud virtinterfaced virtsecretd virtstoraged virtnwfilterd virtnodedevd virtlogd virtlockd";
+      fi
+    - for daemon in $DAEMONS;
+      do
+        LOG_OUTPUTS="1:file:/var/log/libvirt/${daemon}.log";
+        LOG_FILTERS="3:remote 4:event 3:util.json 3:util.object 3:util.dbus 3:util.netlink 3:node_device 3:rpc 3:access 1:*";
+        sudo augtool set /files/etc/libvirt/${daemon}.conf/log_filters "$LOG_FILTERS" &>/dev/null;
+        sudo augtool set /files/etc/libvirt/${daemon}.conf/log_outputs "$LOG_OUTPUTS" &>/dev/null;
+        sudo systemctl --quiet stop ${daemon}.service;
+        sudo systemctl restart ${daemon}.socket;
+      done
+    - sudo virsh net-start default &>/dev/null || true;
+  script:
+    - mkdir logs
+    - cd "$SCRATCH_DIR"
+    - git clone --depth 1 https://gitlab.com/libvirt/libvirt-tck.git
+    - cd libvirt-tck
+    - sudo avocado --config avocado.config run --job-results-dir "$SCRATCH_DIR"/avocado
+  after_script:
+    - test "$CI_JOB_STATUS" = "success" && exit 0;
+    - test -e "$SCRATCH_DIR"/avocado && sudo mv "$SCRATCH_DIR"/avocado/latest/test-results logs/avocado;
+    - sudo coredumpctl info --no-pager > logs/coredumpctl.txt
+    - sudo mv /var/log/libvirt logs/libvirt
+    - sudo chown -R $(whoami):$(whoami) logs
+      # rename all Avocado stderr/stdout logs to *.log so that GitLab's web UI doesn't mangle the MIME type
+    - find logs/avocado/ -type f ! -name "*.log" -exec
+        sh -c 'DIR=$(dirname {}); NAME=$(basename {}); mv $DIR/$NAME{,.log}' \;
+  variables:
+    SCRATCH_DIR: "/tmp/scratch"
+  artifacts:
+    name: logs
+    paths:
+      - logs
+    when: on_failure
+  rules:
+    - if: '$LIBVIRT_CI_INTEGRATION'
+      when: on_success
+    - when: never
+
+centos-stream-8-tests:
+  extends: .integration_tests
+  needs:
+    - x86_64-centos-stream-8
+    - project: libvirt/libvirt-perl
+      job: x86_64-centos-stream-8
+      ref: master
+      artifacts: true
+  variables:
+    # needed by libvirt-gitlab-executor
+    DISTRO: centos-stream-8
+    # can be overridden in forks to set a different runner tag
+    LIBVIRT_CI_INTEGRATION_RUNNER_TAG: redhat-vm-host
+  tags:
+    - $LIBVIRT_CI_INTEGRATION_RUNNER_TAG
+
+centos-stream-9-tests:
+  extends: .integration_tests
+  needs:
+    - x86_64-centos-stream-9
+    - project: libvirt/libvirt-perl
+      job: x86_64-centos-stream-9
+      ref: master
+      artifacts: true
+  variables:
+    # needed by libvirt-gitlab-executor
+    DISTRO: centos-stream-9
+    # can be overridden in forks to set a different runner tag
+    LIBVIRT_CI_INTEGRATION_RUNNER_TAG: redhat-vm-host
+  tags:
+    - $LIBVIRT_CI_INTEGRATION_RUNNER_TAG
+
+fedora-34-tests:
+  extends: .integration_tests
+  needs:
+    - x86_64-fedora-34
+    - project: libvirt/libvirt-perl
+      job: x86_64-fedora-34
+      ref: master
+      artifacts: true
+  variables:
+    # needed by libvirt-gitlab-executor
+    DISTRO: fedora-34
+    # can be overridden in forks to set a different runner tag
+    LIBVIRT_CI_INTEGRATION_RUNNER_TAG: redhat-vm-host
+  tags:
+    - $LIBVIRT_CI_INTEGRATION_RUNNER_TAG
+
+fedora-35-tests:
+  extends: .integration_tests
+  needs:
+    - x86_64-fedora-35
+    - project: libvirt/libvirt-perl
+      job: x86_64-fedora-35
+      ref: master
+      artifacts: true
+  variables:
+    # needed by libvirt-gitlab-executor
+    DISTRO: fedora-35
+    # can be overridden in forks to set a different runner tag
+    LIBVIRT_CI_INTEGRATION_RUNNER_TAG: redhat-vm-host
+  tags:
+    - $LIBVIRT_CI_INTEGRATION_RUNNER_TAG

ci/manifest.yml

@@ -6,7 +6,7 @@ gitlab:
   project: libvirt
 
 targets:
-  centos-8:
+  almalinux-8:
     jobs:
       - arch: x86_64
         variables:
@@ -18,11 +18,30 @@ targets:
           RPM: skip
           CC: clang
 
+  alpine-314:
+    jobs:
+      - arch: x86_64
+
+  alpine-edge:
+    jobs:
+      - arch: x86_64
+        allow-failure: true
+
   centos-stream-8:
     jobs:
       - arch: x86_64
-        variables:
+        artifacts:
-          RPM: skip
+          expire_in: 1 day
+          paths:
+            - libvirt-rpms
+
+  centos-stream-9:
+    jobs:
+      - arch: x86_64
+        artifacts:
+          expire_in: 1 day
+          paths:
+            - libvirt-rpms
 
   debian-10:
     jobs:
@@ -125,11 +144,21 @@ targets:
       - arch: s390x
         allow-failure: true
 
-  fedora-34: x86_64
+  fedora-34:
+    jobs:
+      - arch: x86_64
+        artifacts:
+          expire_in: 1 day
+          paths:
+            - libvirt-rpms
 
   fedora-35:
     jobs:
       - arch: x86_64
+        artifacts:
+          expire_in: 1 day
+          paths:
+            - libvirt-rpms
 
       - arch: mingw32
         allow-failure: true

config.h

@@ -36,18 +36,18 @@
 
 #if defined(__clang_major__) && defined(__clang_minor__)
 # ifdef __apple_build_version__
-#  if __clang_major__ < 5 || (__clang_major__ == 5 && __clang_minor__ < 1)
+#  if __clang_major__ < 10 || (__clang_major__ == 10 && __clang_minor__ < 0)
-#   error You need at least XCode Clang v5.1 to compile libvirt
+#   error You need at least XCode Clang v10.0 to compile libvirt
 #  endif
 # else
-#  if __clang_major__ < 3 || (__clang_major__ == 3 && __clang_minor__ < 4)
+#  if __clang_major__ < 6 || (__clang_major__ == 6 && __clang_minor__ < 4)
-#   error You need at least Clang v3.4 to compile libvirt
+#   error You need at least Clang v6.0 to compile libvirt
 #  endif
 # endif
 #elif defined(__GNUC__) && defined(__GNUC_MINOR__)
-# if __GNUC__ < 4 || (__GNUC__ == 4 && __GNUC_MINOR__ < 8)
+# if __GNUC__ < 7 || (__GNUC__ == 7 && __GNUC_MINOR__ < 4)
-#  error You need at least GCC v4.8 to compile libvirt
+#  error You need at least GCC v7.4.0 to compile libvirt
 # endif
 #else
-# error You either need at least GCC 4.8 or Clang 3.4 or XCode Clang 5.1 to compile libvirt
+# error You either need at least GCC 7.4.0 or Clang 6.0 or XCode Clang 10.0 to compile libvirt
 #endif

docs/api_extension.rst

@@ -73,7 +73,7 @@ The first task is to define the public API. If the new API involves an
 XML extension, you have to enhance the RelaxNG schema and document the
 new elements or attributes:
 
-``docs/schemas/domaincommon.rng         docs/formatdomain.html.in``
+``src/conf/schemas/domaincommon.rng         docs/formatdomain.rst``
 
 If the API extension involves a new function, you have to add a
 declaration in the public header, and arrange to export the function

docs/bugs.html.in

@@ -1,161 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-
-    <h1>Bug reporting</h1>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="security">Security Issues</a></h2>
-
-    <p>
-      If you think that an issue with libvirt may have security
-      implications, <strong>please do not</strong> publicly
-      report it in the bug tracker, mailing lists, or irc. Libvirt
-      has <a href="securityprocess.html">a dedicated process for handling (potential) security issues</a>
-      that should be used instead. So if your issue has security
-      implications, ignore the rest of this page and follow the
-      <a href="securityprocess.html">security process</a> instead.
-    </p>
-
-    <h2><a id="bugtracking">Bug Tracking</a></h2>
-
-    <p>
-      If you are using libvirt binaries from a Linux distribution
-      check below for distribution specific bug reporting policies
-      first.
-    </p>
-
-    <h2><a id="general">General libvirt bug reports</a></h2>
-
-    <p>
-      Bugs in upstream libvirt code should be reported as issues in the
-      appropriate <a href="https://gitlab.com/libvirt">project on GitLab.</a>
-      Before submitting a ticket, check the existing tickets to see if
-      the bug/feature is already tracked.
-    </p>
-    <p>
-      It's always a good idea to file bug reports, as the process of
-      filing the report always makes it easier to describe the
-      problem, and the bug number provides a quick way of referring to
-      the problem.  However, not everybody in the community pays frequent
-      attention to issues, so after you file a bug, asking questions
-      and submitting patches on <a href="contact.html">the libvirt
-      mailing lists</a> will increase your bug's visibility and
-      encourage people to think about your problem.  Don't hesitate to
-      ask questions on the list, as others may know of existing
-      solutions or be interested in collaborating with you on finding
-      a solution.  Patches are always appreciated, and it's likely
-      that someone else has the same problem you do!
-    </p>
-    <p>
-      If you decide to write code, though, before you begin please
-      read the <a href="hacking.html">contributor guidelines</a>,
-      especially the first point: "Discuss any large changes on the
-      mailing list first. Post patches early and listen to feedback."
-      Few development experiences are more discouraging than spending
-      a bunch of time writing a patch only to have someone point out a
-      better approach on list.
-    </p>
-
-    <ul>
-      <li><a href="https://gitlab.com/libvirt/libvirt/-/issues">View libvirt.git tickets</a></li>
-      <li><a href="https://gitlab.com/libvirt/libvirt/-/issues/new">New libvirt.git ticket</a></li>
-    </ul>
-
-    <p>
-      Note bugs in language bindings and other sub-projects should be
-      reported to their corresponding git repository rather than the
-      main libvirt.git linked above.
-    </p>
-
-    <h2><a id="distribution">Linux Distribution specific bug reports</a></h2>
-    <ul>
-      <li>
-        If you are using binaries from <strong>Fedora</strong>, enter
-        tickets against the <code>Fedora</code> product and
-        the <code>libvirt</code> component.
-        <ul>
-          <li><a href="https://bugzilla.redhat.com/buglist.cgi?component=libvirt&amp;product=Fedora">View Fedora libvirt tickets</a></li>
-          <li><a href="https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&amp;component=libvirt">New Fedora libvirt ticket</a></li>
-        </ul>
-      </li>
-      <li>
-        <p>
-          If you are using binaries from <strong>Red Hat Enterprise
-          Linux</strong>, enter tickets against the Red Hat Enterprise
-          Linux product that you're using (e.g., Red Hat Enterprise
-          Linux 6) and the <code>libvirt</code> component.  Red Hat
-          bugzilla has <a href="https://bugzilla.redhat.com">additional guidance</a> about getting support if
-          you are a Red Hat customer.
-        </p>
-      </li>
-      <li>
-        <p>
-          If you are using binaries from another Linux distribution
-          first follow their own bug reporting guidelines.
-        </p>
-      </li>
-      <li>
-        <p>
-          Finally, if you are a contributor to another Linux
-          distribution and would like to have your procedure for
-          filing bugs mentioned here, please mail the libvirt
-          development list.
-        </p>
-      </li>
-    </ul>
-
-
-    <h2><a id="quality">How to file high quality bug reports</a></h2>
-
-    <p>
-      To increase the likelihood of your bug report being addressed it is
-      important to provide as much information as possible. When filing
-      libvirt bugs use this checklist to see if you are providing enough
-      information:
-    </p>
-
-    <ul>
-      <li>The version number of the libvirt build, or SHA1 of the GIT
-        commit</li>
-      <li>The hardware architecture being used</li>
-      <li>The name of the hypervisor (Xen, QEMU, KVM)</li>
-      <li>The XML config of the guest domain if relevant</li>
-      <li>For Xen hypervisor, the domain logfiles from /var/log/xen and
-          /var/log/libvirt/libxl</li>
-      <li>For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu</li>
-    </ul>
-
-    <p>
-      If the bug leads to a tool linked to libvirt crash, then the best
-      is to provide a backtrace along with the scenario used to get the
-      crash, the simplest is to run the program under gdb, reproduce the
-      steps leading to the crash and then issue a gdb "bt -a" command to
-      get the stack trace, attach it to the bug. Note that for the
-      data to be really useful libvirt debug information must be present
-      for example by installing libvirt debuginfo package on Fedora or
-      Red Hat Enterprise Linux (with debuginfo-install libvirt) prior
-      to running gdb.</p>
-    <p>
-      It may also happen that the libvirt daemon itself crashes or gets stuck,
-      in the first case run it (as root) under gdb, and reproduce the sequence
-      leading to the crash, similarly to a normal program provide the
-      "bt" backtrace information to where gdb will have stopped.<br/>
-      But if libvirtd gets stuck, for example seems to stop processing
-      commands, try to attach to the faulty daemon and issue a gdb command
-      "thread apply all bt" to show all the threads backtraces, as in:</p>
-      <pre> #  ps -o etime,pid `pgrep libvirt`
-... note the process id from the output
-# gdb /usr/sbin/libvirtd
-.... some information about gdb and loading debug data
-(gdb) attach $the_daemon_process_id
-....
-(gdb) thread apply all bt
-.... information to attach to the bug
-(gdb)
-</pre>
-
-  </body>
-</html>

docs/bugs.rst

@@ -0,0 +1,125 @@
+.. role:: anchor(raw)
+   :format: html
+
+=============
+Bug reporting
+=============
+
+.. contents::
+
+Security Issues
+---------------
+
+If you think that an issue with libvirt may have security implications, **please
+do not** publicly report it in the bug tracker, mailing lists, or irc. Libvirt
+has `a dedicated process for handling (potential) security
+issues <securityprocess.html>`__ that should be used instead. So if your issue
+has security implications, ignore the rest of this page and follow the `security
+process <securityprocess.html>`__ instead.
+
+Bug Tracking
+------------
+
+If you are using libvirt binaries from a Linux distribution check below for
+distribution specific bug reporting policies first.
+
+General libvirt bug reports
+---------------------------
+
+Bugs in upstream libvirt code should be reported as issues in the appropriate
+`project on GitLab. <https://gitlab.com/libvirt>`__ Before submitting a ticket,
+check the existing tickets to see if the bug/feature is already tracked.
+
+It's always a good idea to file bug reports, as the process of filing the report
+always makes it easier to describe the problem, and the bug number provides a
+quick way of referring to the problem. However, not everybody in the community
+pays frequent attention to issues, so after you file a bug, asking questions and
+submitting patches on `the libvirt mailing lists <contact.html>`__ will increase
+your bug's visibility and encourage people to think about your problem. Don't
+hesitate to ask questions on the list, as others may know of existing solutions
+or be interested in collaborating with you on finding a solution. Patches are
+always appreciated, and it's likely that someone else has the same problem you
+do!
+
+If you decide to write code, though, before you begin please read the
+`contributor guidelines <hacking.html>`__, especially the first point: "Discuss
+any large changes on the mailing list first. Post patches early and listen to
+feedback." Few development experiences are more discouraging than spending a
+bunch of time writing a patch only to have someone point out a better approach
+on list.
+
+-  `View libvirt.git tickets <https://gitlab.com/libvirt/libvirt/-/issues>`__
+-  `New libvirt.git ticket <https://gitlab.com/libvirt/libvirt/-/issues/new>`__
+
+Note bugs in language bindings and other sub-projects should be reported to
+their corresponding git repository rather than the main libvirt.git linked
+above.
+
+Linux Distribution specific bug reports
+---------------------------------------
+
+-  If you are using binaries from **Fedora**, enter tickets against the
+   ``Fedora`` product and the ``libvirt`` component.
+
+   -  `View Fedora libvirt
+      tickets <https://bugzilla.redhat.com/buglist.cgi?component=libvirt&product=Fedora>`__
+   -  `New Fedora libvirt
+      ticket <https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&component=libvirt>`__
+
+-  If you are using binaries from **Red Hat Enterprise Linux**, enter tickets
+   against the Red Hat Enterprise Linux product that you're using (e.g., Red Hat
+   Enterprise Linux 6) and the ``libvirt`` component. Red Hat bugzilla has
+   `additional guidance <https://bugzilla.redhat.com>`__ about getting support
+   if you are a Red Hat customer.
+
+-  If you are using binaries from another Linux distribution first follow their
+   own bug reporting guidelines.
+
+-  Finally, if you are a contributor to another Linux distribution and would
+   like to have your procedure for filing bugs mentioned here, please mail the
+   libvirt development list.
+
+:anchor:`<a id="quality"/>`
+
+How to file high quality bug reports
+------------------------------------
+
+To increase the likelihood of your bug report being addressed it is important to
+provide as much information as possible. When filing libvirt bugs use this
+checklist to see if you are providing enough information:
+
+-  The version number of the libvirt build, or SHA1 of the GIT commit
+-  The hardware architecture being used
+-  The name of the hypervisor (Xen, QEMU, KVM)
+-  The XML config of the guest domain if relevant
+-  For Xen hypervisor, the domain logfiles from /var/log/xen and
+   /var/log/libvirt/libxl
+-  For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu
+
+If the bug leads to a tool linked to libvirt crash, then the best is to provide
+a backtrace along with the scenario used to get the crash, the simplest is to
+run the program under gdb, reproduce the steps leading to the crash and then
+issue a gdb "bt -a" command to get the stack trace, attach it to the bug. Note
+that for the data to be really useful libvirt debug information must be present
+for example by installing libvirt debuginfo package on Fedora or Red Hat
+Enterprise Linux (with debuginfo-install libvirt) prior to running gdb.
+
+| It may also happen that the libvirt daemon itself crashes or gets stuck, in
+  the first case run it (as root) under gdb, and reproduce the sequence leading
+  to the crash, similarly to a normal program provide the "bt" backtrace
+  information to where gdb will have stopped.
+| But if libvirtd gets stuck, for example seems to stop processing commands, try
+  to attach to the faulty daemon and issue a gdb command "thread apply all bt"
+  to show all the threads backtraces, as in:
+
+::
+
+    #  ps -o etime,pid `pgrep libvirt`
+   ... note the process id from the output
+   # gdb /usr/sbin/libvirtd
+   .... some information about gdb and loading debug data
+   (gdb) attach $the_daemon_process_id
+   ....
+   (gdb) thread apply all bt
+   .... information to attach to the bug
+   (gdb)

docs/coding-style.rst

@@ -53,11 +53,16 @@ Struct type names
    All structs should have a 'vir' prefix in their typedef name,
    and each following word should have its first letter in
    uppercase. The struct name should be the same as the typedef
-   name with a leading underscore.
+   name with a leading underscore. For types that are part of the
+   public API, a second typedef should be given for a pointer to
+   the struct with a 'Ptr' suffix. Do not introduce new such
+   typedefs for internal types.
+
    ::
 
-     typedef struct _virHashTable virHashTable;
+     typedef struct _virSomeType virSomeType;
-     struct _virHashTable {
+     typedef virSomeType *virSomeTypePtr;
+     struct _virSomeType {
          ...
      };
 
@@ -69,8 +74,8 @@ Function names
    name prefix should match the object typedef name, otherwise it
    should match the filename. Following this comes the verb /
    action name, and finally an optional subject name. For example,
-   given an object 'virHashTable', all functions should have a
+   given an object 'virSomeType', all functions should have a
-   name 'virHashTable$VERB' or 'virHashTable$VERB$SUBJECT", e.g.
+   name 'virSomeType$VERB' or 'virSomeType$VERB$SUBJECT", e.g.
    'virHashTableLookup' or 'virHashTableGetValue'.
 
 Macro names
@@ -422,25 +427,47 @@ Conditional expressions
 -----------------------
 
 For readability reasons new code should avoid shortening
-comparisons to 0 for numeric types. Boolean and pointer
+comparisons to 0 for numeric types:
-comparisons may be shortened. All long forms are okay:
 
 ::
 
-  virFoo *foos = NULL;
   size nfoos = 0;
+
+  GOOD:
+    if (nfoos != 0)
+    if (nfoos == 0)
+
+  BAD:
+    if (nfoos)
+    if (!nfoos)
+
+Prefer the shortened version for boolean values. Boolean values
+should never be compared against the literal ``true``, as a
+logical non-false value need not be ``1``.
+
+::
+
   bool hasFoos = false;
 
   GOOD:
-    if (!foos)
+    if (hasFoos)
     if (!hasFoos)
-    if (nfoos == 0)
-    if (foos == NULL)
-    if (hasFoos == true)
 
   BAD:
-    if (!nfoos)
+    if (hasFoos == true)
-    if (nfoos)
+    if (hasFoos != false)
+    if (hasFoos == false)
+    if (hasFoos != true)
+
+Pointer comparisons may be shortened. All long forms are okay.
+
+::
+
+  virFoo *foo = NULL;
+
+  GOOD:
+    if (foo)                 # or: if (foo != NULL)
+    if (!foo)                # or: if (foo == NULL)
 
 New code should avoid the ternary operator as much as possible.
 Specifically it must never span more than one line or nest:
@@ -502,19 +529,13 @@ Scalars
 -  In the unusual event that you require a specific width, use a
    standard type like ``int32_t``, ``uint32_t``, ``uint64_t``,
    etc.
--  While using ``bool`` is good for readability, it comes with
+-  While using ``bool`` is good for readability, it comes with a
-   minor caveats:
+   minor caveat: Don't use ``bool`` in places where the type size
-
+   must be constant across all systems, like public interfaces and
-   -  Don't use ``bool`` in places where the type size must be
+   on-the-wire protocols. Note that it would be possible (albeit
-      constant across all systems, like public interfaces and
+   wasteful) to use ``bool`` in libvirt's logical wire protocol,
-      on-the-wire protocols. Note that it would be possible
+   since XDR maps that to its lower-level ``bool_t`` type, which
-      (albeit wasteful) to use ``bool`` in libvirt's logical wire
+   **is** fixed-size.
-      protocol, since XDR maps that to its lower-level ``bool_t``
-      type, which **is** fixed-size.
-   -  Don't compare a bool variable against the literal, ``true``,
-      since a value with a logical non-false value need not be
-      ``1``. I.e., don't write ``if (seen == true) ...``. Rather,
-      write ``if (seen)...``.
 
 Of course, take all of the above with a grain of salt. If you're
 about to use some system interface that requires a type like
@@ -579,6 +600,19 @@ calling another function.
         ...
     }
 
+Prefer variable definitions on separate lines. This allows for smaller,
+easier to understand diffs when changing them. Define variables in the
+smallest possible scope.
+
+::
+
+  GOOD:
+    int count = 0;
+    int nnodes;
+
+  BAD:
+    int count = 0, nnodes;
+
 Attribute annotations
 ---------------------
 
@@ -932,7 +966,6 @@ makes sense:
 
   error:     A path only taken upon return with an error code
   cleanup:   A path taken upon return with success code + optional error
-  no_memory: A path only taken upon return with an OOM error code
   retry:     If needing to jump upwards (e.g., retry on EINTR)
 
 Top-level labels should be indented by one space (putting them on

docs/contact.html.in

@@ -1,116 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Contacting the project contributors</h1>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="security">Security Issues</a></h2>
-
-    <p>
-      If you think that an issue with libvirt may have security
-      implications, <strong>please do not</strong> publicly
-      report it in the bug tracker, mailing lists, or irc. Libvirt
-      has <a href="securityprocess.html">a dedicated process for handling (potential) security issues</a>
-      that should be used instead. So if your issue has security
-      implications, ignore the rest of this page and follow the
-      <a href="securityprocess.html">security process</a> instead.
-    </p>
-
-    <h2><a id="email">Mailing lists</a></h2>
-
-    <p>
-      There are three mailing-lists:
-    </p>
-
-    <dl class="mail">
-      <dt><a href="https://www.redhat.com/mailman/listinfo/libvir-list">libvir-list@redhat.com</a> (for development)</dt>
-      <dd>
-        Archives at <a href="https://www.redhat.com/archives/libvir-list">https://www.redhat.com/archives/libvir-list</a>
-      </dd>
-      <dd>
-        This is a high volume mailing list.  It is a place for discussions
-        about the <strong>development</strong> of libvirt.
-      </dd>
-      <dd>
-        Topics for discussion include:
-        <ul>
-          <li>New features for libvirt</li>
-          <li>Bug fixing of libvirt</li>
-          <li>New hypervisor drivers</li>
-          <li>Development of language bindings for libvirt API</li>
-          <li>Testing and documentation of libvirt</li>
-        </ul>
-      </dd>
-
-      <dt><a href="https://www.redhat.com/mailman/listinfo/libvirt-users">libvirt-users@redhat.com</a> (for users)</dt>
-      <dd>
-        Archives at <a href="https://www.redhat.com/archives/libvirt-users">https://www.redhat.com/archives/libvirt-users</a>
-      </dd>
-      <dd>
-        This is a moderate volume mailing list.  It is a place for discussions
-        involving libvirt <strong>users</strong>.
-      </dd>
-      <dd>
-        Topics for discussion include:
-        <ul>
-          <li>Usage of libvirt / virsh</li>
-          <li>Administration of libvirt</li>
-          <li>Deployment of libvirt with hypervisors</li>
-          <li>Development of applications on top of / using the libvirt API(s)</li>
-          <li>Any other topics along these lines</li>
-        </ul>
-      </dd>
-
-      <dt><a href="https://www.redhat.com/mailman/listinfo/libvirt-announce">libvirt-announce@redhat.com</a> (for release notices)</dt>
-      <dd>
-        Archives at <a href="https://www.redhat.com/archives/libvirt-announce">https://www.redhat.com/archives/libvirt-announce</a>
-      </dd>
-      <dd>
-        This is a low volume mailing list, with restricted posting, for
-        announcements of new libvirt releases.
-      </dd>
-      <dd>
-        Subscribe to just this if you want to be notified of new releases,
-        without subscribing to either of the other mailing lists.
-      </dd>
-
-    </dl>
-
-    <p>
-      It is recommended but not required that you subscribe before posting
-      to the user and development lists.  Posts from non-subscribers will be
-      subject to manual moderation delays.  You can subscribe at the linked
-      web pages above.
-    </p>
-    <p>
-      Patches with explanations and provided as attachments are really
-      appreciated, and should be directed to the development mailing list
-      for review and discussion.
-      Wherever possible, please generate the patches by using
-      <code>git format-patch</code> in a git repository clone.  Further
-      useful information regarding developing libvirt and/or contributing is
-      available on our <a href="hacking.html">Contributor Guidelines</a>
-      page.
-    </p>
-
-    <h2><a id="irc">IRC discussion</a></h2>
-
-    <p>
-      Some of the libvirt developers may be found on IRC on the <a href="https://oftc.net">OFTC IRC</a>
-      network. Use the settings:
-    </p>
-    <ul>
-      <li>server: irc.oftc.net</li>
-      <li>port: 6667 (the usual IRC port)</li>
-      <li>channel: #virt</li>
-    </ul>
-    <p>
-      NB There is no guarantee that someone will be watching or able to reply
-      promptly, so use the mailing-list if you don't get an answer on the IRC
-      channel.
-    </p>
-
-  </body>
-</html>

docs/contact.rst

@@ -0,0 +1,94 @@
+.. role:: anchor(raw)
+   :format: html
+
+===================================
+Contacting the project contributors
+===================================
+
+.. contents::
+
+Security Issues
+---------------
+
+If you think that an issue with libvirt may have security implications, **please
+do not** publicly report it in the bug tracker, mailing lists, or irc. Libvirt
+has `a dedicated process for handling (potential) security
+issues <securityprocess.html>`__ that should be used instead. So if your issue
+has security implications, ignore the rest of this page and follow the `security
+process <securityprocess.html>`__ instead.
+
+:anchor:`<a id="email"/>`
+
+Mailing lists
+-------------
+
+There are three mailing-lists:
+
+**libvir-list@redhat.com** (for development)
+   Archives
+     https://www.redhat.com/archives/libvir-list
+   List info
+     https://www.redhat.com/mailman/listinfo/libvir-list
+
+   This is a high volume mailing list. It is a place for discussions about the
+   **development** of libvirt.
+   Topics for discussion include:
+
+   -  New features for libvirt
+   -  Bug fixing of libvirt
+   -  New hypervisor drivers
+   -  Development of language bindings for libvirt API
+   -  Testing and documentation of libvirt
+
+**libvirt-users@redhat.com** (for users)
+   Archives
+     https://www.redhat.com/archives/libvirt-users
+   List info
+     https://www.redhat.com/mailman/listinfo/libvirt-users
+
+   This is a moderate volume mailing list. It is a place for discussions
+   involving libvirt **users**.
+   Topics for discussion include:
+
+   -  Usage of libvirt / virsh
+   -  Administration of libvirt
+   -  Deployment of libvirt with hypervisors
+   -  Development of applications on top of / using the libvirt API(s)
+   -  Any other topics along these lines
+
+**libvirt-announce@redhat.com** (for release notices)
+   Archives
+     https://www.redhat.com/archives/libvirt-announce
+   List info
+     https://www.redhat.com/mailman/listinfo/libvirt-announce
+
+   This is a low volume mailing list, with restricted posting, for announcements
+   of new libvirt releases.
+   Subscribe to just this if you want to be notified of new releases, without
+   subscribing to either of the other mailing lists.
+
+It is recommended but not required that you subscribe before posting to the user
+and development lists. Posts from non-subscribers will be subject to manual
+moderation delays. You can subscribe at the linked web pages above.
+
+Patches with explanations and provided as attachments are really appreciated,
+and should be directed to the development mailing list for review and
+discussion. Wherever possible, please generate the patches by using
+``git format-patch`` in a git repository clone. Further useful information
+regarding developing libvirt and/or contributing is available on our
+`Contributor Guidelines <hacking.html>`__ page.
+
+:anchor:`<a id="irc"/>`
+
+IRC discussion
+--------------
+
+Some of the libvirt developers may be found on IRC on the `OFTC
+IRC <https://oftc.net>`__ network. Use the settings:
+
+-  server: irc.oftc.net
+-  port: 6667 (the usual IRC port)
+-  channel: #virt
+
+NB There is no guarantee that someone will be watching or able to reply
+promptly, so use the mailing-list if you don't get an answer on the IRC channel.

docs/contribute.html.in

@@ -1,143 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Contributing to libvirt</h1>
-
-    <p>
-      This page provides guidance on how to contribute to the
-      libvirt project.
-    </p>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="skills">Contributions required</a></h2>
-
-    <p>
-      The libvirt project is always looking for new contributors to
-      participate in ongoing activities. While code development is a
-      major part of the project, assistance is needed in many other
-      areas including documentation writing, bug triage, testing,
-      application integration, website / wiki content management,
-      translation, branding, social media and more. The only
-      requirement is an interest in virtualization and desire to
-      help.
-    </p>
-
-    <p>
-      The following is a non-exhaustive list of areas in which
-      people can contribute to libvirt. If you have ideas for
-      other contributions feel free to follow them.
-    </p>
-
-    <ul>
-      <li><strong>Software development</strong>. The official upstream code are
-        kept in various <a href="https://gitlab.com/libvirt/">Git repositories</a>.
-        The core library / daemon (and thus the bulk of coding) is written in C,
-        but there are language bindings written in Python, Perl, Java, Ruby,
-        Php, OCaml and Go. There are also higher level wrappers
-        mapping libvirt into other object frameworks, such GLib,
-        CIM and SNMP. For those interested in working on the core parts of
-        libvirt, the <a href="hacking.html">contributor guidelines</a> are
-        mandatory reading</li>
-      <li><strong>Translation</strong>. All the libvirt modules aim to support
-        translations where appropriate. All translation is
-        handling outside of the normal libvirt review process,
-        using the <a href="https://translate.fedoraproject.org/projects/libvirt/libvirt">Fedora
-        instance</a> of the Weblate tool. Thus people wishing
-        to contribute to translation should join the Fedora
-        translation team</li>
-      <li><strong>Documentation</strong>. There are docbook guides on various
-        aspects of libvirt, particularly application development
-        guides for the C library and Python, and a virsh command
-        reference. There is thus scope for work by people who are
-        familiar with using or developing against libvirt, to
-        write further content for these guides. There is also a
-        need for people to review existing content for copy editing
-        and identifying gaps in the docs</li>
-      <li><strong>Website / wiki curation</strong>. The bulk of the website is
-        maintained in the primary GIT repository, while the wiki
-        site uses mediawiki. In both cases there is a need for
-        people to both write new content and curate existing
-        content to identify outdated information, improve its
-        organization and target gaps.</li>
-      <li><strong>Testing</strong>. There are a number of tests suites that can run
-        automated tests against libvirt. The coverage of the tests
-        is never complete, so there is a need for people to create
-        new test suites and / or provide environments to actually
-        run the tests in a variety of deployment scenarios.</li>
-      <li><strong>Code analysis</strong>. The libvirt project has access to the coverity
-        tool to run static analysis against the codebase, however,
-        there are other types of code analysis that can be useful.
-        In particular fuzzing of the inputs can be very effective
-        at identifying problematic edge cases.</li>
-      <li><strong>Security handling</strong>. Downstream (operating system) vendors
-        who distribute libvirt may wish to propose a person to
-        be part of the security handling team, to get early access
-        to information about forthcoming vulnerability fixes.</li>
-      <li><strong>Evangelism</strong>. Work done by the project is of no benefit
-        unless the (potential) user community knows that it
-        exists. Thus it is critically important to the health
-        and future growth of the project, that there are a people
-        who evangelize the work created by the project. This can
-        take many forms, writing blog posts (about usage of features,
-        personal user experiences, areas for future work, and more),
-        syndicating docs and blogs via social media, giving user
-        group and/or conference talks about libvirt.</li>
-      <li><strong>User assistance</strong>. Since documentation
-        is never perfect, there are inevitably cases where users
-        will struggle to attain a deployment goal they have, or
-        run into trouble with managing an existing deployment.
-        While some users may be able to contact a software vendor
-        to obtain support, it is common to rely on community help
-        forums such as <a href="contact.html#email">libvirt users
-          mailing list</a>, or sites such as
-        <a href="https://stackoverflow.com/questions/tagged/libvirt">stackoverflow.</a>
-        People who are familiar with libvirt and have ability &amp;
-        desire to help other users are encouraged to participate in
-        these help forums.</li>
-    </ul>
-
-    <h2><a id="comms">Communication</a></h2>
-
-    <p>
-      For full details on contacting other project contributors
-      read the <a href="contact.html">contact</a> page. There
-      are two main channels that libvirt uses for communication
-      between contributors:
-    </p>
-
-    <h3><a id="email">Mailing lists</a></h3>
-
-    <p>
-      The project has a number of
-      <a href="contact.html#email">mailing lists</a> for
-      general communication between contributors.
-      In general any design discussions and review
-      of contributions will take place on the mailing
-      lists, so it is important for all contributors
-      to follow the traffic.
-    </p>
-
-    <h3><a id="irc">Instant messaging / chat</a></h3>
-
-    <p>
-      Contributors to libvirt are encouraged to join the
-      <a href="contact.html#irc">IRC channel</a> used by
-      the project, where they can have live conversations
-      with others members.
-    </p>
-
-    <h2><a id="outreach">Student / outreach coding programs</a></h2>
-
-    <p>
-      Since 2016, the libvirt project directly participates as an
-      organization in the <a href="https://wiki.libvirt.org/page/Google_Summer_of_Code_Ideas">Google Summer of Code program</a>. Prior to
-      this the project had a number of students in the program
-      via a joint application with the QEMU project. People are
-      encouraged to look at both the libvirt and QEMU programs
-      to identify potentially interesting projects to work on.
-    </p>
-
-  </body>
-</html>

docs/contribute.rst

@@ -0,0 +1,105 @@
+=======================
+Contributing to libvirt
+=======================
+
+This page provides guidance on how to contribute to the libvirt project.
+
+.. contents::
+
+Contributions required
+----------------------
+
+The libvirt project is always looking for new contributors to participate in
+ongoing activities. While code development is a major part of the project,
+assistance is needed in many other areas including documentation writing, bug
+triage, testing, application integration, website / wiki content management,
+translation, branding, social media and more. The only requirement is an
+interest in virtualization and desire to help.
+
+The following is a non-exhaustive list of areas in which people can contribute
+to libvirt. If you have ideas for other contributions feel free to follow them.
+
+-  **Software development**. The official upstream code are kept in various `Git
+   repositories <https://gitlab.com/libvirt/>`__. The core library / daemon (and
+   thus the bulk of coding) is written in C, but there are language bindings
+   written in Python, Perl, Java, Ruby, Php, OCaml and Go. There are also higher
+   level wrappers mapping libvirt into other object frameworks, such GLib, CIM
+   and SNMP. For those interested in working on the core parts of libvirt, the
+   `contributor guidelines <hacking.html>`__ are mandatory reading
+-  **Translation**. All the libvirt modules aim to support translations where
+   appropriate. All translation is handling outside of the normal libvirt review
+   process, using the `Fedora
+   instance <https://translate.fedoraproject.org/projects/libvirt/libvirt>`__ of
+   the Weblate tool. Thus people wishing to contribute to translation should
+   join the Fedora translation team
+-  **Documentation**. There are docbook guides on various aspects of libvirt,
+   particularly application development guides for the C library and Python, and
+   a virsh command reference. There is thus scope for work by people who are
+   familiar with using or developing against libvirt, to write further content
+   for these guides. There is also a need for people to review existing content
+   for copy editing and identifying gaps in the docs
+-  **Website / wiki curation**. The bulk of the website is maintained in the
+   primary GIT repository, while the wiki site uses mediawiki. In both cases
+   there is a need for people to both write new content and curate existing
+   content to identify outdated information, improve its organization and target
+   gaps.
+-  **Testing**. There are a number of tests suites that can run automated tests
+   against libvirt. The coverage of the tests is never complete, so there is a
+   need for people to create new test suites and / or provide environments to
+   actually run the tests in a variety of deployment scenarios.
+-  **Code analysis**. The libvirt project has access to the coverity tool to run
+   static analysis against the codebase, however, there are other types of code
+   analysis that can be useful. In particular fuzzing of the inputs can be very
+   effective at identifying problematic edge cases.
+-  **Security handling**. Downstream (operating system) vendors who distribute
+   libvirt may wish to propose a person to be part of the security handling
+   team, to get early access to information about forthcoming vulnerability
+   fixes.
+-  **Evangelism**. Work done by the project is of no benefit unless the
+   (potential) user community knows that it exists. Thus it is critically
+   important to the health and future growth of the project, that there are a
+   people who evangelize the work created by the project. This can take many
+   forms, writing blog posts (about usage of features, personal user
+   experiences, areas for future work, and more), syndicating docs and blogs via
+   social media, giving user group and/or conference talks about libvirt.
+-  **User assistance**. Since documentation is never perfect, there are
+   inevitably cases where users will struggle to attain a deployment goal they
+   have, or run into trouble with managing an existing deployment. While some
+   users may be able to contact a software vendor to obtain support, it is
+   common to rely on community help forums such as `libvirt users mailing
+   list <contact.html#email>`__, or sites such as
+   `stackoverflow. <https://stackoverflow.com/questions/tagged/libvirt>`__
+   People who are familiar with libvirt and have ability & desire to help other
+   users are encouraged to participate in these help forums.
+
+Communication
+-------------
+
+For full details on contacting other project contributors read the
+`contact <contact.html>`__ page. There are two main channels that libvirt uses
+for communication between contributors:
+
+Mailing lists
+~~~~~~~~~~~~~
+
+The project has a number of `mailing lists <contact.html#email>`__ for general
+communication between contributors. In general any design discussions and review
+of contributions will take place on the mailing lists, so it is important for
+all contributors to follow the traffic.
+
+Instant messaging / chat
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Contributors to libvirt are encouraged to join the `IRC
+channel <contact.html#irc>`__ used by the project, where they can have live
+conversations with others members.
+
+Student / outreach coding programs
+----------------------------------
+
+Since 2016, the libvirt project directly participates as an organization in the
+`Google Summer of Code
+program <https://wiki.libvirt.org/page/Google_Summer_of_Code_Ideas>`__. Prior to
+this the project had a number of students in the program via a joint application
+with the QEMU project. People are encouraged to look at both the libvirt and
+QEMU programs to identify potentially interesting projects to work on.

docs/daemons.rst

@@ -209,13 +209,6 @@ controlled via the system unit files
   ``libvirtd.socket``, ``libvirtd-ro.socket`` and ``libvirtd-admin.socket`` unit
   files.
 
-Systemd releases prior to version 227 lacked support for passing the activation
-socket unit names into the service. When using these old versions, the
-``tcp_port``, ``tls_port`` and ``unix_sock_dir`` settings in ``libvirtd.conf``
-must be changed in lock-step with the equivalent settings in the unit files to
-ensure that ``libvirtd`` can identify the sockets.
-
-
 Modular driver daemons
 ======================
 
@@ -354,13 +347,6 @@ controlled via the system unit files:
   ``virt${DRIVER}d.socket``, ``virt${DRIVER}d-ro.socket`` and
   ``virt${DRIVER}d-admin.socket`` unit files.
 
-Systemd releases prior to version 227 lacked support for passing the activation
-socket unit names into the service. When using these old versions, the
-``unix_sock_dir`` setting in ``virt${DRIVER}d.conf`` must be changed in
-lock-step with the equivalent setting in the unit files to ensure that
-``virt${DRIVER}d`` can identify the sockets.
-
-
 Switching to modular daemons
 ----------------------------
 
@@ -435,6 +421,58 @@ host first.
       $ systemctl enable virtproxyd-tls.socket
       $ systemctl start virtproxyd-tls.socket
 
+Checking whether modular/monolithic mode is in use
+==================================================
+
+New distributions are likely to use the modular mode although the upgrade
+process preserves whichever mode was in use before the upgrade.
+
+To determine whether modular or monolithic mode is in use on a host running
+``systemd`` as the init system you can take the following steps:
+
+#. Check whether the modular daemon infrastructure is in use
+
+   First check whether the modular daemon you are interested (see
+   `Modular driver daemons`_ for a summary of which daemons are provided by
+   libvirt) in is running:
+
+   #. Check ``.socket`` for socket activated services
+
+     ::
+
+       # systemctl is-active virtqemud.socket
+       active
+
+   #. Check ``.service`` for always-running daemons
+
+     ::
+
+       # systemctl is-active virtqemud.service
+       active
+
+   If either of the above is ``active`` your system is using the modular daemons.
+
+#. Check whether the monolithic daemon is in use
+
+   #. Check ``libvirtd.socket``
+
+     ::
+
+       # systemctl is-active libvirtd.socket
+       active
+
+   #. Check ``libvirtd.service`` for always-running daemon
+
+     ::
+
+       # systemctl is-active libvirtd.service
+       active
+
+   If either of the above is ``active`` your system is using the monolithic
+   daemon.
+
+#. To determine which of the above will be in use on the next boot of the system,
+   substitute ``is-enabled`` for ``is-active`` in the above examples.
 
 Proxy daemon
 ============
@@ -587,12 +625,6 @@ controlled via the system unit files:
   independently controlled via the ``ListenStream`` parameter in any of the
   ``virtlogd.socket`` and ``virtlogd-admin.socket`` unit files.
 
-Systemd releases prior to version 227 lacked support for passing the activation
-socket unit names into the service. When using these old versions, the
-``unix_sock_dir`` setting in ``virtlogd.conf`` must be changed in
-lock-step with the equivalent setting in the unit files to ensure that
-``virtlogd`` can identify the sockets.
-
 Locking daemon
 ==============
 
@@ -681,8 +713,23 @@ controlled via the system unit files:
   independently controlled via the ``ListenStream`` parameter in any of the
   ``virtlockd.socket`` and ``virtlockd-admin.socket`` unit files.
 
-Systemd releases prior to version 227 lacked support for passing the activation
+Changing command line options for daemons
-socket unit names into the service. When using these old versions, the
+=========================================
-``unix_sock_dir`` setting in ``virtlockd.conf`` must be changed in
+
-lock-step with the equivalent setting in the unit files to ensure that
+Two ways exist to override the defaults in the provided service files:
-``virtlockd`` can identify the sockets.
+either a systemd "drop-in" configuration file, or a ``/etc/sysconfig/$daemon``
+file must be created.  For example, to change the command line option
+for a debug session of ``libvirtd``, create a file
+``/etc/systemd/system/libvirtd.service.d/debug.conf`` with the following content:
+
+   ::
+
+      [Unit]
+      Description=Virtualization daemon, with override from debug.conf
+
+      [Service]
+      Environment=G_DEBUG=fatal-warnings
+      Environment=LIBVIRTD_ARGS="--listen --verbose"
+
+After changes to systemd "drop-in" configuration files it is required to run
+``systemctl daemon-reload``.

docs/developer-tooling.rst

@@ -1,13 +0,0 @@
-=================
-Developer tooling
-=================
-
-libvirt includes support for some useful development tools right
-in its source repository, meaning users will be able to take
-advantage of them without little or no configuration. Examples
-include:
-
--  `color_coded <https://github.com/jeaye/color_coded>`__, a vim
-   plugin for libclang-powered semantic syntax highlighting;
--  `YouCompleteMe <http://valloric.github.io/YouCompleteMe/>`__, a
-   vim plugin for libclang-powered semantic code completion.

docs/devguide.html.in

@@ -1,42 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>libvirt Application Development Guides</h1>
-
-    <p>
-      The libvirt API is accessible from a number of programming languages.
-      At this time, there are application development guides available
-      which cover the C API and the Python API. Of the two, the Python guide
-      is currently the more comprehensive document.
-    </p>
-
-    <ul>
-      <li><a href="https://libvirt.org/docs/libvirt-appdev-guide/en-US/html/">Application Development Guide (C language) HTML</a></li>
-      <li><a href="https://libvirt.org/docs/libvirt-appdev-guide/en-US/pdf/">Application Development Guide (C language) PDF</a></li>
-      <li><a href="https://libvirt.org/docs/libvirt-appdev-guide-python/en-US/html/">Application Development Guide (Python language) HTML</a></li>
-      <li><a href="https://libvirt.org/docs/libvirt-appdev-guide-python/en-US/pdf/">Application Development Guide (Python language) PDF</a></li>
-    </ul>
-
-    <h2>Contributing content</h2>
-
-    <p>
-      These guides are written in DocBook and published with the
-      publican tool, which is also used for Fedora and Red Hat
-      documentation. The original content is provided in GIT and
-      any contributions to the guide are welcome.
-    </p>
-
-    <pre>
-# C language
-$ git clone <a href="https://libvirt.org/git/?p=libvirt-appdev-guide.git">https://libvirt.org/git/libvirt-appdev-guide.git</a>
-
-# Python language
-$ git clone <a href="https://libvirt.org/git/?p=libvirt-appdev-guide-python.git">https://libvirt.org/git/libvirt-appdev-guide-python.git</a>
-
-# Publican Style/Theme
-$ git clone <a href="https://libvirt.org/git/?p=libvirt-publican.git">https://libvirt.org/git/libvirt-publican.git</a>
-    </pre>
-
-  </body>
-</html>

docs/docs.html.in

@@ -16,6 +16,9 @@
         <dt><a href="windows.html">Windows</a></dt>
         <dd>Downloads for Windows</dd>
 
+        <dt><a href="macos.html">macOS</a></dt>
+        <dd>Working with libvirt on macOS</dd>
+
         <dt><a href="migration.html">Migration</a></dt>
         <dd>Migrating guests between machines</dd>
 

docs/downloads.html.in

@@ -1,661 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Downloads</h1>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="releases">Project modules</a></h2>
-
-    <p>
-      The libvirt project maintains a number of inter-related modules beyond
-      the core C library/daemon.
-    </p>
-
-    <table class="top_table downloads">
-      <thead>
-        <tr>
-          <th>Module</th>
-          <th>Releases</th>
-          <th>GIT Repo</th>
-          <th>Bug Tracker</th>
-          <th>GIT Mirrors</th>
-          <th>Resources</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr>
-          <td>libvirt</td>
-          <td>
-            <a href="https://libvirt.org/sources/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt">github</a>
-          </td>
-          <td>
-            <a href="html/index.html">api ref</a>
-            <a href="news.html">changes</a>
-          </td>
-        </tr>
-        <tr>
-          <th colspan="7">Language bindings</th>
-        </tr>
-        <tr>
-          <td>C#</td>
-          <td>
-            <a href="https://libvirt.org/sources/csharp/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-csharp">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-csharp/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-csharp.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-csharp">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Go</td>
-          <td>
-            <a href="https://libvirt.org/go/libvirt">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-go-module">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-go-module/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-go-module.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-go-module">github</a>
-          </td>
-          <td>
-            <a href="https://pkg.go.dev/libvirt.org/go/libvirt">api ref</a>
-          </td>
-        </tr>
-        <tr>
-          <td>Java</td>
-          <td>
-            <a href="https://libvirt.org/sources/java/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-java">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-java/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-java.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-java">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>OCaml</td>
-          <td>
-            <a href="https://libvirt.org/sources/ocaml/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-ocaml">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-ocaml/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-ocaml.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-ocaml">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Perl (Sys::Virt)</td>
-          <td>
-            <a href="https://metacpan.org/release/Sys-Virt/">cpan</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-perl">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-perl/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-perl.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-perl">github</a>
-          </td>
-          <td>
-            <a href="https://metacpan.org/release/Sys-Virt/">api ref</a>
-            <a href="https://libvirt.org/git/?p=libvirt-perl.git;a=blob;f=Changes;hb=HEAD">changes</a>
-          </td>
-        </tr>
-        <tr>
-          <td>PHP</td>
-          <td>
-            <a href="https://libvirt.org/sources/php/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-php">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-php/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-php.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-php">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Python</td>
-          <td>
-            <a href="https://libvirt.org/sources/python/">libvirt</a>
-            <a href="https://pypi.python.org/pypi/libvirt-python">pypi</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-python">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-python/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-python.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-python">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Ruby</td>
-          <td>
-            <a href="https://libvirt.org/sources/ruby/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-ruby">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-ruby/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-ruby.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-ruby">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Rust</td>
-          <td>
-            <a href="https://crates.io/crates/virt">crates.io</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-rust">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-rust/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-rust.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-rust">github</a>
-          </td>
-          <td>
-            <a href="https://docs.rs/virt">api ref</a>
-          </td>
-        </tr>
-        <tr>
-          <th colspan="7">Integration modules</th>
-        </tr>
-        <tr>
-          <td>GLib / GConfig / GObject</td>
-          <td>
-            <a href="https://libvirt.org/sources/glib/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-glib">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-glib/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-glib.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-glib">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Go XML</td>
-          <td>
-            <a href="https://libvirt.org/go/libvirtxml">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-go-xml-module">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-go-xml-module/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-go-xml-module.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-go-xml-module">github</a>
-          </td>
-          <td>
-            <a href="https://pkg.go.dev/libvirt.org/go/libvirtxml">api ref</a>
-          </td>
-        </tr>
-        <tr>
-          <td>D-Bus</td>
-          <td>
-            <a href="https://libvirt.org/sources/dbus/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-dbus">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-dbus/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-dbus.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-dbus">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Console Proxy</td>
-          <td>
-            <a href="https://libvirt.org/sources/consoleproxy/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-console-proxy">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-console-proxy/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-console-proxy.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-console-proxy">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>CIM provider</td>
-          <td>
-            <a href="https://libvirt.org/sources/CIM/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-cim">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-cim/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-cim.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-cim">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>CIM utils</td>
-          <td>
-            <a href="https://libvirt.org/sources/CIM/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libcmpiutil">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libcmpiutil/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libcmpiutil.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libcmpiutil">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>SNMP</td>
-          <td>
-            <a href="https://libvirt.org/sources/snmp/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-snmp">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-snmp/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-snmp.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-snmp">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Application Sandbox</td>
-          <td>
-            <a href="https://libvirt.org/sources/sandbox/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-sandbox">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-sandbox/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-sandbox.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-sandbox">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <th colspan="7">Testing</th>
-        </tr>
-        <tr>
-          <td>TCK</td>
-          <td>
-            <a href="https://libvirt.org/sources/tck/">libvirt</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-tck">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-tck/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-tck.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-tck">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Test API</td>
-          <td></td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-test-API">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-test-API/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-test-API.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-test-API">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Continuous Integration Config</td>
-          <td></td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-ci">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-ci/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-ci.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-ci">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>CIM Test</td>
-          <td></td>
-          <td>
-            <a href="https://gitlab.com/libvirt/cimtest">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/cimtest/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=cimtest.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/cimtest">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <th colspan="7">Documentation</th>
-        </tr>
-        <tr>
-          <td>Publican Brand</td>
-          <td></td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-publican">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-publican/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-publican.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-publican">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>App Development Guide</td>
-          <td></td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-appdev-guide">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-appdev-guide/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-appdev-guide.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-appdev-guide">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>App Development Guide Python</td>
-          <td></td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-appdev-guide-python">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-appdev-guide-python/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-appdev-guide-python.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-appdev-guide-python">github</a>
-          </td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>virsh Command Reference</td>
-          <td></td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-virshcmdref">gitlab</a>
-          </td>
-          <td>
-            <a href="https://gitlab.com/libvirt/libvirt-virshcmdref/-/issues">issues</a>
-          </td>
-          <td class="gitmirror">
-            <a href="https://libvirt.org/git/?p=libvirt-virshcmdref.git;a=summary">libvirt</a>
-            <a href="https://github.com/libvirt/libvirt-virshcmdref">github</a>
-          </td>
-          <td></td>
-        </tr>
-      </tbody>
-    </table>
-
-    <h2>Primary download site</h2>
-
-    <p>
-      Most modules have releases made available for download on the project
-      site via HTTPS. Some modules are instead made available at alternative
-      locations, for example, the Perl binding is made available only on CPAN.
-    </p>
-
-    <ul>
-      <li><a href="https://libvirt.org/sources/">libvirt.org HTTPS server</a></li>
-    </ul>
-
-    <h2><a id="schedule">Primary release schedule</a></h2>
-
-    <p>
-      The core libvirt module follows a time based plan, with releases made
-      once a month on the 1st of each month give or take a few days. The only
-      exception is at the start of the year where there are two 6 weeks gaps
-      (first release in the middle of Jan, then skip the Feb release), giving
-      a total of 11 releases a year. The Python and Perl modules will aim to
-      release at the same time as the core libvirt module. Other modules have
-      independent ad-hoc releases with no fixed time schedule.
-    </p>
-
-    <h2><a id="numbering">Release numbering</a></h2>
-
-    <p>
-      Since libvirt 2.0.0, a time based version numbering rule
-      is applied to the core library releases. As such, the changes
-      in version number have do not have any implications with respect
-      to the scope of features or bugfixes included, the stability of
-      the code, or the API / ABI compatibility (libvirt API / ABI is
-      guaranteed stable forever). The rules applied for changing the
-      libvirt version number are:
-    </p>
-
-    <dl>
-      <dt><code>major</code></dt>
-      <dd>incremented by 1 for the first release of the year (the
-        Jan 15th release)</dd>
-      <dt><code>minor</code></dt>
-      <dd>reset to 0 with every major increment, otherwise incremented by 1
-        for each monthly release from git master</dd>
-      <dt><code>micro</code></dt>
-      <dd>always 0 for releases from git master, incremented by 1
-        for each stable maintenance release</dd>
-    </dl>
-
-    <p>
-      Prior to 2.0.0, the major/minor numbers were incremented
-      fairly arbitrarily, and maintenance releases appended a
-      fourth digit. The language bindings will aim to use the
-      same version number as the most recent core library API
-      they support. The other modules have their own distinct
-      release numbering sequence, though they generally aim
-      to follow the above rules for incrementing major/minor/micro
-      digits.
-    </p>
-
-    <h2><a id="maintenance">Maintenance releases</a></h2>
-    <p>
-      In the git repository are several stable maintenance branches
-      for the core library, matching the
-      pattern <code>v<i>major</i>.<i>minor</i>-maint</code>;
-      these branches are forked off the corresponding
-      <code>v<i>major</i>.<i>minor</i>.0</code> formal
-      release, and may have further releases of the
-      form <code>v<i>major</i>.<i>minor</i>.<i>micro</i></code>.
-      These maintenance branches should only contain bug fixes, and no
-      new features, backported from the master branch, and are
-      supported as long as at least one downstream distribution
-      expresses interest in a given branch.  These maintenance
-      branches are considered during CVE analysis. In contrast
-      to the primary releases which are made once a month, there
-      is no formal schedule for the maintenance releases, which
-      are made whenever there is a need to make available key
-      bugfixes to downstream consumers. The language bindings
-      and other modules generally do not provide stable branch
-      releases.
-    </p>
-
-    <p>
-      For more details about contents of maintenance releases, see
-      <a href="https://wiki.libvirt.org/page/Maintenance_Releases">the
-      wiki page</a>.
-    </p>
-
-    <h2><a id="git">GIT source repository</a></h2>
-
-    <p>
-      All modules maintained by the libvirt project have their primary
-      source available in the <a href="https://libvirt.org/git/">project GIT server</a>.
-      Each module can be cloned anonymously using:
-    </p>
-
-    <pre>
-git clone https://libvirt.org/git/[module name].git</pre>
-
-    <p>
-      The <code>git://</code> protocol is also available if desired, but
-      <code>https://</code> is encouraged, since it is more reliable when
-      faced with strict firewalls.
-    </p>
-
-    <pre>
-git clone git://libvirt.org/[module name].git</pre>
-
-    <p>
-      In addition to this primary repository, there are the following read-only git
-      repositories which mirror the master one. Note that we currently do not
-      use the full set of features on these mirrors (e.g. pull requests on
-      GitHub, so please don't use them). All patch review and discussion only
-      occurs on the <a href="contact.html">libvir-list</a> mailing list. Also
-      note that some repositories listed below allow HTTP checkouts too.
-    </p>
-
-    <pre>
-<a href="https://github.com/libvirt/">https://github.com/libvirt/</a>
-<a href="https://gitlab.com/libvirt/libvirt">https://gitlab.com/libvirt/</a></pre>
-
-    <h2><a id="keys">Signing keys</a></h2>
-
-    <p>
-      Source RPM packages and tarballs for libvirt and libvirt-python published
-      on this project site are signed with a GPG signature. You should always
-      verify the package signature before using the source to compile binary
-      packages. The following key is currently used to generate the GPG
-      signatures:
-    </p>
-    <pre>
-pub  4096R/10084C9C 2020-07-20 Jiří Denemark &lt;jdenemar@redhat.com&gt;
-Fingerprint=453B 6531 0595 5628 5547  1199 CA68 BE80 1008 4C9C
-</pre>
-
-    <p>
-      It can be downloaded from
-      <a href="https://libvirt.org/sources/gpg_key.asc">this site</a> or from
-      public GPG key servers.
-    </p>
-
-    <p>
-      Releases prior to libvirt-6.6 were signed with the following GPG key:
-    </p>
-
-    <pre>
-pub   dsa1024 2000-05-31 [SC]
-C744 15BA 7C9C 7F78 F02E  1DC3 4606 B8A5 DE95 BC1F
-uid           [ unknown] Daniel Veillard (Red Hat work email) &lt;veillard@redhat.com&gt;
-uid           [ unknown] Daniel Veillard &lt;Daniel.Veillard@w3.org&gt;
-    </pre>
-
-    <pre>
------BEGIN PGP SIGNED MESSAGE-----
-Hash: SHA256
-
-Starting from libvirt-6.6.0 the upstream releases will be done by Jiří Denemark
-signed with his PGP key:
-
-pub  4096R/10084C9C 2020-07-20 Jiří Denemark &lt;jdenemar@redhat.com&gt;
-Fingerprint=453B 6531 0595 5628 5547  1199 CA68 BE80 1008 4C9C
-
-This message is signed by the old signing key which was used for previous
-releases.
------BEGIN PGP SIGNATURE-----
-
-iQEzBAEBCAAdFiEE20ZoG7ka3OoXD6LUFViLJllr6l0FAl/8H9cACgkQFViLJllr
-6l3iVwgAm9n703/QoIfPbxT5qGQzWK6LNriEcG2R9MLgFcW+UuGA9cqIBLhH1RaJ
-q7Gc3gK0dgE2HAF6DxuG5+nkDY6LdmonLOVFWQkMCh41JHFrV6tw8y9hc/RNOb/m
-gFAl4HpwYisjTRvsTRcpR3ElK6lI0Yu4GY4gJxj5qH4L5exR+kkylwuAxqP+wuyY
-b/L/tP76F4+Q9SSPj0M01NRVC7V8m3yvnok5y374vtxvRFome0WMELn81vphxBLx
-X7LQ1LyjvRs0HhN5MutJES5FYDzArTYZfZJozJgE465XrHxMMCbXbZ/AgAs/aD+5
-x+m2mFplbS57tMEoMBP/ezbbL5wpvA==
-=KnaO
------END PGP SIGNATURE-----
-    </pre>
-
-  </body>
-</html>

docs/downloads.rst

@@ -0,0 +1,392 @@
+=========
+Downloads
+=========
+
+.. contents::
+
+Project modules
+---------------
+
+The libvirt project maintains a number of inter-related modules beyond the core
+C library/daemon.
+
+Libvirt
+~~~~~~~
+
+.. list-table::
+  :header-rows: 1
+
+  * - Module
+    - Releases
+    - GIT Repo
+    - Bug Tracker
+    - GIT Mirrors
+    - Resources
+
+  * - libvirt
+    - `libvirt <https://libvirt.org/sources/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt>`__
+    - `issues <https://gitlab.com/libvirt/libvirt/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt>`__
+    - `api ref <html/index.html>`__
+      `changes <news.html>`__
+
+Language bindings
+~~~~~~~~~~~~~~~~~
+
+.. list-table::
+  :header-rows: 1
+
+  * - Module
+    - Releases
+    - GIT Repo
+    - Bug Tracker
+    - GIT Mirrors
+    - Resources
+
+  * - C#
+    - `libvirt <https://libvirt.org/sources/csharp/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-csharp>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-csharp/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-csharp>`__
+    -
+
+  * - Go
+    - `libvirt <https://libvirt.org/go/libvirt>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-go-module>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-go-module/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-go-module>`__
+    - `api ref <https://pkg.go.dev/libvirt.org/go/libvirt>`__
+
+  * - Java
+    - `libvirt <https://libvirt.org/sources/java/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-java>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-java/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-java>`__
+    -
+
+  * - OCaml
+    - `libvirt <https://libvirt.org/sources/ocaml/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-ocaml>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-ocaml/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-ocaml>`__
+    -
+
+  * - Perl (Sys::Virt)
+    - `cpan <https://metacpan.org/release/Sys-Virt/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-perl>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-perl/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-perl>`__
+    - `api ref <https://metacpan.org/release/Sys-Virt/>`__
+      `changes <https://libvirt.org/git/?p=libvirt-perl.git;a=blob;f=Changes;hb=HEAD>`__
+
+  * - PHP
+    - `libvirt <https://libvirt.org/sources/php/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-php>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-php/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-php>`__
+    -
+
+  * - Python
+    - `libvirt <https://libvirt.org/sources/python/>`__
+      `pypi <https://pypi.python.org/pypi/libvirt-python>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-python>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-python/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-python>`__
+    -
+
+  * - Ruby
+    - `libvirt <https://libvirt.org/sources/ruby/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-ruby>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-ruby/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-ruby>`__
+    -
+
+  * - Rust
+    - `crates.io <https://crates.io/crates/virt>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-rust>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-rust/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-rust>`__
+    - `api ref <https://docs.rs/virt>`__
+
+Integration modules
+~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+  :header-rows: 1
+
+  * - Module
+    - Releases
+    - GIT Repo
+    - Bug Tracker
+    - GIT Mirrors
+    - Resources
+
+  * - GLib / GConfig / GObject
+    - `libvirt <https://libvirt.org/sources/glib/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-glib>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-glib/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-glib>`__
+    -
+
+  * - Go XML
+    - `libvirt <https://libvirt.org/go/libvirtxml>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-go-xml-module>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-go-xml-module/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-go-xml-module>`__
+    - `api ref <https://pkg.go.dev/libvirt.org/go/libvirtxml>`__
+
+  * - D-Bus
+    - `libvirt <https://libvirt.org/sources/dbus/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-dbus>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-dbus/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-dbus>`__
+    -
+
+  * - Console Proxy
+    - `libvirt <https://libvirt.org/sources/consoleproxy/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-console-proxy>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-console-proxy/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-console-proxy>`__
+    -
+
+  * - CIM provider
+    - `libvirt <https://libvirt.org/sources/CIM/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-cim>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-cim/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-cim>`__
+    -
+
+  * - CIM utils
+    - `libvirt <https://libvirt.org/sources/CIM/>`__
+    - `gitlab <https://gitlab.com/libvirt/libcmpiutil>`__
+    - `issues <https://gitlab.com/libvirt/libcmpiutil/-/issues>`__
+    - `github <https://github.com/libvirt/libcmpiutil>`__
+    -
+
+  * - SNMP
+    - `libvirt <https://libvirt.org/sources/snmp/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-snmp>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-snmp/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-snmp>`__
+    -
+
+  * - Application Sandbox
+    - `libvirt <https://libvirt.org/sources/sandbox/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-sandbox>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-sandbox/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-sandbox>`__
+    -
+
+Testing
+~~~~~~~
+
+.. list-table::
+  :header-rows: 1
+
+  * - Module
+    - Releases
+    - GIT Repo
+    - Bug Tracker
+    - GIT Mirrors
+
+  * - TCK
+    - `libvirt <https://libvirt.org/sources/tck/>`__
+    - `gitlab <https://gitlab.com/libvirt/libvirt-tck>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-tck/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-tck>`__
+
+  * - Test API
+    -
+    - `gitlab <https://gitlab.com/libvirt/libvirt-test-API>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-test-API/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-test-API>`__
+
+  * - Continuous Integration Config
+    -
+    - `gitlab <https://gitlab.com/libvirt/libvirt-ci>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-ci/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-ci>`__
+
+  * - CIM Test
+    -
+    - `gitlab <https://gitlab.com/libvirt/cimtest>`__
+    - `issues <https://gitlab.com/libvirt/cimtest/-/issues>`__
+    - `github <https://github.com/libvirt/cimtest>`__
+
+Documentation
+~~~~~~~~~~~~~
+
+.. list-table::
+  :header-rows: 1
+
+  * - Module
+    - GIT Repo
+    - Bug Tracker
+    - GIT Mirrors
+
+  * - Publican Brand
+    - `gitlab <https://gitlab.com/libvirt/libvirt-publican>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-publican/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-publican>`__
+
+  * - App Development Guide
+    - `gitlab <https://gitlab.com/libvirt/libvirt-appdev-guide>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-appdev-guide/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-appdev-guide>`__
+
+  * - App Development Guide Python
+    - `gitlab <https://gitlab.com/libvirt/libvirt-appdev-guide-python>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-appdev-guide-python/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-appdev-guide-python>`__
+
+  * - virsh Command Reference
+    - `gitlab <https://gitlab.com/libvirt/libvirt-virshcmdref>`__
+    - `issues <https://gitlab.com/libvirt/libvirt-virshcmdref/-/issues>`__
+    - `github <https://github.com/libvirt/libvirt-virshcmdref>`__
+
+Primary download site
+---------------------
+
+Most modules have releases made available for download on the project site via
+HTTPS. Some modules are instead made available at alternative locations, for
+example, the Perl binding is made available only on CPAN.
+
+-  `libvirt.org HTTPS server <https://libvirt.org/sources/>`__
+
+Primary release schedule
+------------------------
+
+The core libvirt module follows a time based plan, with releases made once a
+month on the 1st of each month give or take a few days. The only exception is at
+the start of the year where there are two 6 weeks gaps (first release in the
+middle of Jan, then skip the Feb release), giving a total of 11 releases a year.
+The Python and Perl modules will aim to release at the same time as the core
+libvirt module. Other modules have independent ad-hoc releases with no fixed
+time schedule.
+
+Release numbering
+-----------------
+
+Since libvirt 2.0.0, a time based version numbering rule is applied to the core
+library releases. As such, the changes in version number have do not have any
+implications with respect to the scope of features or bugfixes included, the
+stability of the code, or the API / ABI compatibility (libvirt API / ABI is
+guaranteed stable forever). The rules applied for changing the libvirt version
+number are:
+
+``major``
+   incremented by 1 for the first release of the year (the Jan 15th release)
+``minor``
+   reset to 0 with every major increment, otherwise incremented by 1 for each
+   monthly release from git master
+``micro``
+   always 0 for releases from git master, incremented by 1 for each stable
+   maintenance release
+
+Prior to 2.0.0, the major/minor numbers were incremented fairly arbitrarily, and
+maintenance releases appended a fourth digit. The language bindings will aim to
+use the same version number as the most recent core library API they support.
+The other modules have their own distinct release numbering sequence, though
+they generally aim to follow the above rules for incrementing major/minor/micro
+digits.
+
+Maintenance releases
+--------------------
+
+In the git repository are several stable maintenance branches for the core
+library, matching the pattern ``vmajor.minor-maint``; these branches are forked
+off the corresponding ``vmajor.minor.0`` formal release, and may have further
+releases of the form ``vmajor.minor.micro``. These maintenance branches should
+only contain bug fixes, and no new features, backported from the master branch,
+and are supported as long as at least one downstream distribution expresses
+interest in a given branch. These maintenance branches are considered during CVE
+analysis. In contrast to the primary releases which are made once a month, there
+is no formal schedule for the maintenance releases, which are made whenever
+there is a need to make available key bugfixes to downstream consumers. The
+language bindings and other modules generally do not provide stable branch
+releases.
+
+For more details about contents of maintenance releases, see `the wiki
+page <https://wiki.libvirt.org/page/Maintenance_Releases>`__.
+
+GIT source repository
+---------------------
+
+All modules maintained by the libvirt project have their primary source
+available in the `libvirt group on GitLab <https://gitlab.com/libvirt/>`__.
+Each module can be cloned anonymously using:
+
+::
+
+   git clone https://gitlab.com/libvirt/[module name].git
+
+In addition to this primary repository, there are mirrored read-only git
+repositories on GitHub:
+
+::
+
+   https://github.com/libvirt/
+
+And there are also read-only mirrors on libvirt.org:
+
+::
+
+   git clone https://libvirt.org/git/[module name].git
+
+Note that for most repositories, development happens via merge requests
+on GitLab. However, for the main `libvirt.git` repository all patch review and
+discussion only occurs on the `libvir-list <contact.html>`__ mailing list.
+
+The GitHub repository is read-only and pull requests and issues there are ignored.
+
+Signing keys
+------------
+
+Source RPM packages and tarballs for libvirt and libvirt-python published on
+this project site are signed with a GPG signature. You should always verify the
+package signature before using the source to compile binary packages. The
+following key is currently used to generate the GPG signatures:
+
+::
+
+   pub  4096R/10084C9C 2020-07-20 Jiří Denemark <jdenemar@redhat.com>
+   Fingerprint=453B 6531 0595 5628 5547  1199 CA68 BE80 1008 4C9C
+
+It can be downloaded from `this
+site <https://libvirt.org/sources/gpg_key.asc>`__ or from public GPG key
+servers.
+
+Releases prior to libvirt-6.6 were signed with the following GPG key:
+
+::
+
+   pub   dsa1024 2000-05-31 [SC]
+   C744 15BA 7C9C 7F78 F02E  1DC3 4606 B8A5 DE95 BC1F
+   uid           [ unknown] Daniel Veillard (Red Hat work email) <veillard@redhat.com>
+   uid           [ unknown] Daniel Veillard <Daniel.Veillard@w3.org>
+
+::
+
+   -----BEGIN PGP SIGNED MESSAGE-----
+   Hash: SHA256
+
+   Starting from libvirt-6.6.0 the upstream releases will be done by Jiří Denemark
+   signed with his PGP key:
+
+   pub  4096R/10084C9C 2020-07-20 Jiří Denemark <jdenemar@redhat.com>
+   Fingerprint=453B 6531 0595 5628 5547  1199 CA68 BE80 1008 4C9C
+
+   This message is signed by the old signing key which was used for previous
+   releases.
+   -----BEGIN PGP SIGNATURE-----
+
+   iQEzBAEBCAAdFiEE20ZoG7ka3OoXD6LUFViLJllr6l0FAl/8H9cACgkQFViLJllr
+   6l3iVwgAm9n703/QoIfPbxT5qGQzWK6LNriEcG2R9MLgFcW+UuGA9cqIBLhH1RaJ
+   q7Gc3gK0dgE2HAF6DxuG5+nkDY6LdmonLOVFWQkMCh41JHFrV6tw8y9hc/RNOb/m
+   gFAl4HpwYisjTRvsTRcpR3ElK6lI0Yu4GY4gJxj5qH4L5exR+kkylwuAxqP+wuyY
+   b/L/tP76F4+Q9SSPj0M01NRVC7V8m3yvnok5y374vtxvRFome0WMELn81vphxBLx
+   X7LQ1LyjvRs0HhN5MutJES5FYDzArTYZfZJozJgE465XrHxMMCbXbZ/AgAs/aD+5
+   x+m2mFplbS57tMEoMBP/ezbbL5wpvA==
+   =KnaO
+   -----END PGP SIGNATURE-----

docs/drivers.html.in

@@ -1,44 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Internal drivers</h1>
-
-    <ul>
-      <li><a href="#hypervisor">Hypervisor drivers</a></li>
-      <li><a href="storage.html">Storage drivers</a></li>
-      <li><a href="drvnodedev.html">Node device driver</a></li>
-      <li><a href="drvsecret.html">Secret driver</a></li>
-    </ul>
-
-    <p>
-      The libvirt public API delegates its implementation to one or
-      more internal drivers, depending on the <a href="uri.html">connection URI</a>
-      passed when initializing the library. There is always a hypervisor driver
-      active, and if the libvirt daemon is available there will usually be a
-      network and storage driver active.
-    </p>
-
-    <h2><a id="hypervisor">Hypervisor drivers</a></h2>
-
-    <p>
-      The hypervisor drivers currently supported by libvirt are:
-    </p>
-
-    <ul>
-      <li><strong><a href="drvlxc.html">LXC</a></strong> - Linux Containers</li>
-      <li><strong><a href="drvopenvz.html">OpenVZ</a></strong></li>
-      <li><strong><a href="drvqemu.html">QEMU</a></strong></li>
-      <li><strong><a href="drvtest.html">Test</a></strong> - Used for testing</li>
-      <li><strong><a href="drvvbox.html">VirtualBox</a></strong></li>
-      <li><strong><a href="drvesx.html">VMware ESX</a></strong></li>
-      <li><strong><a href="drvvmware.html">VMware Workstation/Player</a></strong></li>
-      <li><strong><a href="drvxen.html">Xen</a></strong></li>
-      <li><strong><a href="drvhyperv.html">Microsoft Hyper-V</a></strong></li>
-      <li><strong><a href="drvvirtuozzo.html">Virtuozzo</a></strong></li>
-      <li><strong><a href="drvbhyve.html">Bhyve</a></strong> - The BSD Hypervisor</li>
-      <li><strong><a href="drvch.html">Cloud Hypervisor</a></strong></li>
-    </ul>
-
-  </body>
-</html>

docs/drivers.rst

@@ -0,0 +1,31 @@
+================
+Internal drivers
+================
+
+-  `Hypervisor drivers <#hypervisor-drivers>`__
+-  `Storage drivers <storage.html>`__
+-  `Node device driver <drvnodedev.html>`__
+-  `Secret driver <drvsecret.html>`__
+
+The libvirt public API delegates its implementation to one or more internal
+drivers, depending on the `connection URI <uri.html>`__ passed when initializing
+the library. There is always a hypervisor driver active, and if the libvirt
+daemon is available there will usually be a network and storage driver active.
+
+Hypervisor drivers
+------------------
+
+The hypervisor drivers currently supported by libvirt are:
+
+-  `LXC <drvlxc.html>`__ - Linux Containers
+-  `OpenVZ <drvopenvz.html>`__
+-  `QEMU <drvqemu.html>`__
+-  `Test <drvtest.html>`__ - Used for testing
+-  `VirtualBox <drvvbox.html>`__
+-  `VMware ESX <drvesx.html>`__
+-  `VMware Workstation/Player <drvvmware.html>`__
+-  `Xen <drvxen.html>`__
+-  `Microsoft Hyper-V <drvhyperv.html>`__
+-  `Virtuozzo <drvvirtuozzo.html>`__
+-  `Bhyve <drvbhyve.html>`__ - The BSD Hypervisor
+-  `Cloud Hypervisor <drvch.html>`__

docs/drvqemu.rst

@@ -1,13 +1,18 @@
 .. role:: since
 .. role:: removed
 
-==========================
+==============================
-KVM/QEMU hypervisor driver
+QEMU/KVM/HVF hypervisor driver
-==========================
+==============================
 
 The libvirt KVM/QEMU driver can manage any QEMU emulator from version 2.11.0 or
 later.
 
+It supports multiple QEMU accelerators: software
+emulation also known as TCG, hardware-assisted virtualization on Linux
+with KVM and hardware-assisted virtualization on macOS with
+Hypervisor.framework (:since:`since 8.1.0`).
+
 .. contents::
 
 Project Links
@@ -15,6 +20,7 @@ Project Links
 
 -  The `KVM <https://www.linux-kvm.org/>`__ Linux hypervisor
 -  The `QEMU <https://wiki.qemu.org/Index.html>`__ emulator
+-  `Hypervisor.framework`<https://developer.apple.com/documentation/hypervisor>__` reference
 
 Deployment pre-requisites
 -------------------------
@@ -27,6 +33,9 @@ Deployment pre-requisites
 -  **KVM hypervisor**: The driver will probe ``/usr/bin`` for the presence of
    ``qemu-kvm`` and ``/dev/kvm`` device node. If both are found, then KVM fully
    virtualized, hardware accelerated guests will be available.
+-  **Hypervisor.framework (HVF)**: The driver will probe ``sysctl`` for the
+   presence of ``Hypervisor.framework``. If it is found and QEMU is newer than
+   2.12, then it will be possible to create hardware accelerated guests.
 
 Connections to QEMU driver
 --------------------------
@@ -571,6 +580,63 @@ reconfigure libvirtd.
 
 *DO NOT* use in production.
 
+Overriding properties of QEMU devices
+-------------------------------------
+
+For development or testing the ``<qemu:override>`` tag allows to override
+specific properties of devices instantiated by libvirt.
+
+The ``<qemu:device>`` sub-element groups overrides for a device identified via
+the ``alias`` attribute. The alias corresponds to the ``<alias name=''>``
+property of a device. It's strongly recommended to use user-specified aliases
+for devices with overridden properties.
+
+Sub element ``<qemu:frontend>`` encapsulates all overrides of properties for the
+device frontend and overrides what libvirt formats via ``-device``.
+:since:`Since 8.2.0`.
+
+The individual properties are overridden by a ``<qemu:property>`` element. The
+``name`` specifies the name of the property to override. In case when libvirt
+doesn't configure the property a property with the name is added to the
+commandline. The ``type`` attribute specifies a type of the argument used. The
+type must correspond with the type that is expected by QEMU. Supported values
+for the type attribute are: ``string``, ``number``, ``bool`` (allowed values for
+``bool`` are ``true`` and ``false``) and ``remove``. The ``remove`` type is
+special and instructs libvirt to remove the property without replacement.
+
+The overrides are applied only to initial device configuration passed to QEMU
+via the commandline. Later hotplug operations will not apply any modifications.
+
+Configuring override for a device alias which is not used or attempting to
+remove a device property which is not formatted by libvirt will cause failure
+to startup the VM.
+
+*Note:* The libvirt project doesn't guarantee any form of compatibility and
+stability of devices with overridden properties. The domain is tainted when
+such configuration is used.
+
+Example:
+
+::
+
+   <domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
+     <name>testvm</name>
+
+      [...]
+
+     <qemu:override>
+       <qemu:device alias='ua-devalias'>
+         <qemu:frontend>
+           <qemu:property name='propname1' type='string' value='test'/>
+           <qemu:property name='propname2' type='unsigned' value='123'/>
+           <qemu:property name='propname2' type='signed' value='-123'/>
+           <qemu:property name='propname3' type='bool' value='false'/>
+           <qemu:property name='propname4' type='remove'/>
+         </qemu:frontend>
+       </qemu:device>
+     </qemu:override>
+   </domain>
+
 Example domain XML config
 -------------------------
 
@@ -634,3 +700,36 @@ KVM hardware accelerated guest on i686
        <graphics type='vnc' port='-1' keymap='de'/>
      </devices>
    </domain>
+
+HVF hardware accelerated guest on x86_64
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+   <domain type='hvf'>
+     <name>hvf-demo</name>
+     <uuid>4dea24b3-1d52-d8f3-2516-782e98a23fa0</uuid>
+     <memory>131072</memory>
+     <vcpu>1</vcpu>
+     <os>
+       <type arch="x86_64">hvm</type>
+     </os>
+     <features>
+       <acpi/>
+     </features>
+     <clock sync="localtime"/>
+     <devices>
+       <emulator>/usr/local/bin/qemu-system-x86_64</emulator>
+       <controller type='scsi' index='0' model='virtio-scsi'/>
+       <disk type='volume' device='disk'>
+         <driver name='qemu' type='qcow2'/>
+         <source pool='default' volume='myos'/>
+         <target bus='scsi' dev='sda'/>
+       </disk>
+       <interface type='user'>
+         <mac address='24:42:53:21:52:45'/>
+         <model type='virtio'/>
+       </interface>
+       <graphics type='vnc' port='-1'/>
+     </devices>
+   </domain>

docs/errors.html.in

@@ -1,84 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1 >Handling of errors</h1>
-    <p>The main goals of libvirt when it comes to error handling are:</p>
-    <ul>
-      <li>provide as much detail as possible</li>
-      <li>provide the information as soon as possible</li>
-      <li>dont force the library user into one style of error handling</li>
-    </ul>
-    <p>As result the library provide both synchronous, callback based and
-asynchronous error reporting. When an error happens in the library code the
-error is logged, allowing to retrieve it later and if the user registered an
-error callback it will be called synchronously. Once the call to libvirt ends
-the error can be detected by the return value and the full information for
-the last logged error can be retrieved.</p>
-    <p>To avoid as much as possible troubles with a global variable in a
-multithreaded environment, libvirt will associate when possible the errors to
-the current connection they are related to, that way the error is stored in a
-dynamic structure which can be made thread specific. Error callback can be
-set specifically to a connection with</p>
-    <p>So error handling in the code is the following:</p>
-    <ol>
-      <li>if the error can be associated to a connection for example when failing
-    to look up a domain
-    <ol><li>if there is a callback associated to the connection set with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
-        call it with the error information</li><li>otherwise if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
-        call it with the error information</li><li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
-        which is the default error function of the library issuing the error
-        on stderr</li><li>save the error in the connection for later retrieval with <a href="html/libvirt-virterror.html#virConnGetLastError">virConnGetLastError</a></li></ol></li>
-      <li>otherwise like when failing to create a hypervisor connection:
-    <ol><li>if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>,
-        call it with the error information</li><li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>
-        which is the default error function of the library issuing the error
-        on stderr</li><li>save the error in the connection for later retrieval with <a href="html/libvirt-virterror.html#virGetLastError">virGetLastError</a></li></ol></li>
-    </ol>
-    <p>In all cases the error information is provided as a <a href="html/libvirt-virterror.html#virErrorPtr">virErrorPtr</a> pointer to
-read-only structure <a href="html/libvirt-virterror.html#virError">virError</a> containing the
-following fields:</p>
-    <ul>
-      <li>code: an error number from the <a href="html/libvirt-virterror.html#virErrorNumber">virErrorNumber</a>
-  enum</li>
-      <li>domain: an enum indicating which part of libvirt raised the error see
-    <a href="html/libvirt-virterror.html#virErrorDomain">virErrorDomain</a></li>
-      <li>level: the error level, usually VIR_ERR_ERROR, though there is room for
-    warnings like VIR_ERR_WARNING</li>
-      <li>message: the full human-readable formatted string of the error</li>
-      <li>conn: if available a pointer to the <a href="html/libvirt-libvirt-host.html#virConnectPtr">virConnectPtr</a>
-    connection to the hypervisor where this happened</li>
-      <li>dom: if available a pointer to the <a href="html/libvirt-libvirt-domain.html#virDomainPtr">virDomainPtr</a> domain
-    targeted in the operation</li>
-    </ul>
-    <p>and then extra raw information about the error which may be initialized
-to 0 or NULL if unused</p>
-    <ul>
-      <li>str1, str2, str3: string information, usually str1 is the error
-    message format</li>
-      <li>int1, int2: integer information</li>
-    </ul>
-    <p>So usually, setting up specific error handling with libvirt consist of
-registering a handler with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a> or
-with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>,
-check the value of the code value, take appropriate action, if needed let
-libvirt print the error on stderr by calling <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>.
-For asynchronous error handing, set such a function doing nothing to avoid
-the error being reported on stderr, and call virConnGetLastError or
-virGetLastError when an API call returned an error value. It can be a good
-idea to use <a href="html/libvirt-virterror.html#virResetLastError">virResetError</a> or <a href="html/libvirt-virterror.html#virConnResetLastError">virConnResetLastError</a>
-once an error has been processed fully.</p>
-    <p>At the python level, there only a global reporting callback function at
-this point, see the error.py example about it:</p>
-    <pre>def handler(ctxt, err):
-    global errno
-
-    #print "handler(%s, %s)" % (ctxt, err)
-    errno = err
-
-libvirt.registerErrorHandler(handler, 'context') </pre>
-    <p>the second argument to the registerErrorHandler function is passed as the
-first argument of the callback like in the C version. The error is a tuple
-containing the same field as a virError in C, but cast to Python.</p>
-  </body>
-</html>

docs/errors.rst

@@ -0,0 +1,109 @@
+==================
+Handling of errors
+==================
+
+The main goals of libvirt when it comes to error handling are:
+
+-  provide as much detail as possible
+-  provide the information as soon as possible
+-  dont force the library user into one style of error handling
+
+As result the library provide both synchronous, callback based and asynchronous
+error reporting. When an error happens in the library code the error is logged,
+allowing to retrieve it later and if the user registered an error callback it
+will be called synchronously. Once the call to libvirt ends the error can be
+detected by the return value and the full information for the last logged error
+can be retrieved.
+
+To avoid as much as possible troubles with a global variable in a multithreaded
+environment, libvirt will associate when possible the errors to the current
+connection they are related to, that way the error is stored in a dynamic
+structure which can be made thread specific. Error callback can be set
+specifically to a connection with
+
+So error handling in the code is the following:
+
+#. if the error can be associated to a connection for example when failing to
+   look up a domain
+
+   #. if there is a callback associated to the connection set with
+      `virConnSetErrorFunc <html/libvirt-virterror.html#virConnSetErrorFunc>`__,
+      call it with the error information
+   #. otherwise if there is a global callback set with
+      `virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__, call it
+      with the error information
+   #. otherwise call
+      `virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__
+      which is the default error function of the library issuing the error on
+      stderr
+   #. save the error in the connection for later retrieval with
+      `virConnGetLastError <html/libvirt-virterror.html#virConnGetLastError>`__
+
+#. otherwise like when failing to create a hypervisor connection:
+
+   #. if there is a global callback set with
+      `virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__, call it
+      with the error information
+   #. otherwise call
+      `virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__
+      which is the default error function of the library issuing the error on
+      stderr
+   #. save the error in the connection for later retrieval with
+      `virGetLastError <html/libvirt-virterror.html#virGetLastError>`__
+
+In all cases the error information is provided as a
+`virErrorPtr <html/libvirt-virterror.html#virErrorPtr>`__ pointer to read-only
+structure `virError <html/libvirt-virterror.html#virError>`__ containing the
+following fields:
+
+-  code: an error number from the
+   `virErrorNumber <html/libvirt-virterror.html#virErrorNumber>`__ enum
+-  domain: an enum indicating which part of libvirt raised the error see
+   `virErrorDomain <html/libvirt-virterror.html#virErrorDomain>`__
+-  level: the error level, usually VIR_ERR_ERROR, though there is room for
+   warnings like VIR_ERR_WARNING
+-  message: the full human-readable formatted string of the error
+-  conn: if available a pointer to the
+   `virConnectPtr <html/libvirt-libvirt-host.html#virConnectPtr>`__ connection
+   to the hypervisor where this happened
+-  dom: if available a pointer to the
+   `virDomainPtr <html/libvirt-libvirt-domain.html#virDomainPtr>`__ domain
+   targeted in the operation
+
+and then extra raw information about the error which may be initialized to 0 or
+NULL if unused
+
+-  str1, str2, str3: string information, usually str1 is the error message
+   format
+-  int1, int2: integer information
+
+So usually, setting up specific error handling with libvirt consist of
+registering a handler with
+`virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__ or with
+`virConnSetErrorFunc <html/libvirt-virterror.html#virConnSetErrorFunc>`__, check
+the value of the code value, take appropriate action, if needed let libvirt
+print the error on stderr by calling
+`virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__. For
+asynchronous error handing, set such a function doing nothing to avoid the error
+being reported on stderr, and call virConnGetLastError or virGetLastError when
+an API call returned an error value. It can be a good idea to use
+`virResetError <html/libvirt-virterror.html#virResetLastError>`__ or
+`virConnResetLastError <html/libvirt-virterror.html#virConnResetLastError>`__
+once an error has been processed fully.
+
+At the python level, there only a global reporting callback function at this
+point, see the error.py example about it:
+
+::
+
+   def handler(ctxt, err):
+       global errno
+
+       #print "handler(%s, %s)" % (ctxt, err)
+       errno = err
+
+   libvirt.registerErrorHandler(handler, 'context')
+
+the second argument to the registerErrorHandler function is passed as the first
+argument of the callback like in the C version. The error is a tuple containing
+the same field as a virError in C, but cast to Python.

docs/formatcaps.html.in

@@ -51,7 +51,10 @@
       <dt><code>topology</code></dt>
       <dd>This element embodies the host internal topology. Management
       applications may want to learn this information when orchestrating new
-      guests - e.g. due to reduce inter-NUMA node transfers.</dd>
+      guests - e.g. due to reduce inter-NUMA node transfers. Note that the
+      <code>sockets</code> value reported here is per-NUMA-node; this is in
+      contrast to the value given in domain definitions, which is interpreted
+      as a total number of sockets for the domain.</dd>
 
       <dt><code>secmodel</code></dt>
       <dd>To find out default security labels for different security models you

docs/formatdomain.rst

@@ -20,7 +20,8 @@ Element and attribute overview
 
 The root element required for all virtual machines is named ``domain``. It has
 two attributes, the ``type`` specifies the hypervisor used for running the
-domain. The allowed values are driver specific, but include "xen", "kvm", "qemu"
+domain. The allowed values are driver specific, but include "xen", "kvm",
+"hvf" (:since:`since 8.1.0 and QEMU 2.12`), "qemu"
 and "lxc". The second attribute is ``id`` which is a unique integer identifier
 for the running guest machine. Inactive machines have no id value.
 
@@ -110,12 +111,19 @@ harddisk, cdrom, network) determining where to obtain/find the boot image.
 
 ::
 
+   <!-- Xen with fullvirt loader -->
    ...
-   <os firmware='efi'>
+   <os>
      <type>hvm</type>
-     <loader readonly='yes' secure='no' type='rom'>/usr/lib/xen/boot/hvmloader</loader>
+     <loader>/usr/lib/xen/boot/hvmloader</loader>
-     <nvram template='/usr/share/OVMF/OVMF_VARS.fd'>/var/lib/libvirt/nvram/guest_VARS.fd</nvram>
      <boot dev='hd'/>
+   </os>
+   ...
+
+   <!-- QEMU with default firmware, serial console and SMBIOS -->
+   ...
+   <os>
+     <type>hvm</type>
      <boot dev='cdrom'/>
      <bootmenu enable='yes' timeout='3000'/>
      <smbios mode='sysinfo'/>
@@ -123,6 +131,25 @@ harddisk, cdrom, network) determining where to obtain/find the boot image.
    </os>
    ...
 
+   <!-- QEMU with UEFI manual firmware and secure boot -->
+   ...
+   <os>
+     <type>hvm</type>
+     <loader readonly='yes' secure='yes' type='pflash'>/usr/share/OVMF/OVMF_CODE.fd</loader>
+     <nvram template='/usr/share/OVMF/OVMF_VARS.fd'>/var/lib/libvirt/nvram/guest_VARS.fd</nvram>
+     <boot dev='hd'/>
+   </os>
+   ...
+
+   <!-- QEMU with automatic UEFI firmware and secure boot -->
+   ...
+   <os firmware='efi'>
+     <type>hvm</type>
+     <loader secure='yes'/>
+     <boot dev='hd'/>
+   </os>
+   ...
+
 ``firmware``
    The ``firmware`` attribute allows management applications to automatically
    fill ``<loader/>`` and ``<nvram/>`` elements and possibly enable some
@@ -977,7 +1004,7 @@ Memory Backing
        <locked/>
        <source type="file|anonymous|memfd"/>
        <access mode="shared|private"/>
-       <allocation mode="immediate|ondemand"/>
+       <allocation mode="immediate|ondemand" threads='8'/>
        <discard/>
      </memoryBacking>
      ...
@@ -1026,8 +1053,10 @@ influence how virtual memory pages are backed by host pages.
    Using the ``mode`` attribute, specify if the memory is to be "shared" or
    "private". This can be overridden per numa node by ``memAccess``.
 ``allocation``
-   Using the ``mode`` attribute, specify when to allocate the memory by
+   Using the optional ``mode`` attribute, specify when to allocate the memory by
-   supplying either "immediate" or "ondemand".
+   supplying either "immediate" or "ondemand". :since:`Since 8.2.0` it is
+   possible to set the number of threads that hypervisor uses to allocate
+   memory via ``threads`` attribute.
 ``discard``
    When set and supported by hypervisor the memory content is discarded just
    before guest shuts down (or when DIMM module is unplugged). Please note that
@@ -1425,7 +1454,8 @@ In case no restrictions need to be put on CPU model and its features, a simpler
       :since:`Since 7.1.0` with the QEMU driver.
 
    Both ``host-model`` and ``host-passthrough`` modes make sense when a domain
-   can run directly on the host CPUs (for example, domains with type ``kvm``).
+   can run directly on the host CPUs (for example, domains with type ``kvm``
+   or ``hvf``).
    The actual host CPU is irrelevant for domains with emulated virtual CPUs
    (such as domains with type ``qemu``). However, for backward compatibility
    ``host-model`` may be implemented even for domains running on emulated CPUs
@@ -1459,12 +1489,12 @@ In case no restrictions need to be put on CPU model and its features, a simpler
    The ``topology`` element specifies requested topology of virtual CPU provided
    to the guest. Four attributes, ``sockets``, ``dies``, ``cores``, and
    ``threads``, accept non-zero positive integer values. They refer to the
-   number of CPU sockets per NUMA node, number of dies per socket, number of
+   total number of CPU sockets, number of dies per socket, number of cores per
-   cores per die, and number of threads per core, respectively. The ``dies``
+   die, and number of threads per core, respectively. The ``dies`` attribute is
-   attribute is optional and will default to 1 if omitted, while the other
+   optional and will default to 1 if omitted, while the other attributes are all
-   attributes are all mandatory. Hypervisors may require that the maximum number
+   mandatory. Hypervisors may require that the maximum number of vCPUs specified
-   of vCPUs specified by the ``cpus`` element equals to the number of vcpus
+   by the ``cpus`` element equals to the number of vcpus resulting from the
-   resulting from the topology.
+   topology.
 ``feature``
    The ``cpu`` element can contain zero or more ``feature`` elements used to
    fine-tune features provided by the selected CPU model. The list of known
@@ -1634,14 +1664,13 @@ ACPI Heterogeneous Memory Attribute Table
    <cpu>
      ...
      <numa>
-       <cell id='0' cpus='0-3' memory='512000' unit='KiB' discard='yes'/>
+       <cell id='0' cpus='0-3' memory='2097152' unit='KiB' discard='yes'>
-       <cell id='1' cpus='4-7' memory='512000' unit='KiB' memAccess='shared'/>
-       <cell id='3' cpus='0-3' memory='2097152' unit='KiB'>
          <cache level='1' associativity='direct' policy='writeback'>
            <size value='10' unit='KiB'/>
            <line value='8' unit='B'/>
          </cache>
        </cell>
+       <cell id='1' cpus='4-7' memory='512000' unit='KiB' memAccess='shared'/>
        <interconnects>
          <latency initiator='0' target='0' type='access' value='5'/>
          <latency initiator='0' target='0' cache='1' type='access' value='10'/>
@@ -1749,7 +1778,7 @@ Each of these states allow for the same four possible actions.
    The domain will be terminated and then restarted with a new name. (Only
    supported by the libxl hypervisor driver.)
 
-QEMU/KVM supports the ``on_poweroff`` and ``on_reboot`` events handling the
+QEMU/KVM/HVF supports the ``on_poweroff`` and ``on_reboot`` events handling the
 ``destroy`` and ``restart`` actions, but the combination of ``on_poweroff`` set
 to ``restart`` and ``on_reboot`` set to ``destroy`` is forbidden.
 
@@ -1884,8 +1913,8 @@ are:
    Physical address extension mode allows 32-bit guests to address more than 4
    GB of memory.
 ``acpi``
-   ACPI is useful for power management, for example, with KVM guests it is
+   ACPI is useful for power management, for example, with KVM or HVF guests it
-   required for graceful shutdown to work.
+   is required for graceful shutdown to work.
 ``apic``
    APIC allows the use of programmable IRQ management. :since:`Since 0.10.2
    (QEMU only)` there is an optional attribute ``eoi`` with values ``on`` and
@@ -2593,13 +2622,14 @@ paravirtualized driver is specified via the ``disk`` element.
       Indicates the default behavior of the disk during disk snapshots:
       "``internal``" requires a file format such as qcow2 that can store both
       the snapshot and the data changes since the snapshot; "``external``" will
-      separate the snapshot from the live data; and "``no``" means the disk will
+      separate the snapshot from the live data; "``no``" means the disk will
-      not participate in snapshots. Read-only disks default to "``no``", while
+      not participate in snapshots; and ``manual`` allows snapshotting done via
-      the default for other disks depends on the hypervisor's capabilities. Some
+      an unmanaged storage provider. Read-only disks default to "``no``", while
-      hypervisors allow a per-snapshot choice as well, during `domain snapshot
+      the default for other disks depends on the hypervisor's capabilities.
-      creation <formatsnapshot.html>`__. Not all snapshot modes are supported;
+      Some hypervisors allow a per-snapshot choice as well, during `domain
-      for example, enabling snapshots with a transient disk generally does not
+      snapshot creation <formatsnapshot.html>`__. Not all snapshot modes are
-      make sense. :since:`Since 0.9.5`
+      supported; for example, enabling snapshots with a transient disk
+      generally does not make sense. :since:`Since 0.9.5`
 
 ``source``
    Representation of the disk ``source`` depends on the disk ``type`` attribute
@@ -2626,7 +2656,9 @@ paravirtualized driver is specified via the ``disk`` element.
       be enabled by setting the ``tls`` attribute to ``yes``. For the QEMU
       hypervisor, usage of a TLS environment can also be globally controlled on
       the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` in
-      /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` )
+      /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` ) :since:`Since 8.2.0`
+      the optional attribute ``tlsHostname`` can be used to override the
+      expected host name of the NBD server used for TLS certificate verification.
 
       For protocols ``http`` and ``https`` an optional attribute ``query``
       specifies the query string. ( :since:`Since 6.2.0` )
@@ -6194,14 +6226,16 @@ A video device.
 
    You can provide the amount of video memory in kibibytes (blocks of 1024
    bytes) using ``vram``. This is supported only for guest type of "vz", "qemu",
-   "vbox", "vmx" and "xen". If no value is provided the default is used. If the
+   "kvm", "hvf", "vbox", "vmx" and "xen".
+   If no value is provided the default is used. If the
    size is not a power of two it will be rounded to closest one.
 
    The number of screen can be set using ``heads``. This is supported only for
-   guests type of "vz", "kvm", "vbox" and "vmx".
+   guests type of "vz", "kvm", "hvf", "vbox" and "vmx".
 
-   For guest type of "kvm" or "qemu" and model type "qxl" there are optional
+   For guest type of "kvm", "hvf" or "qemu" and model type "qxl" there are
-   attributes. Attribute ``ram`` ( :since:`since 1.0.2` ) specifies the size of
+   optional attributes.
+   Attribute ``ram`` ( :since:`since 1.0.2` ) specifies the size of
    the primary bar, while the attribute ``vram`` specifies the secondary bar
    size. If ``ram`` or ``vram`` are not supplied a default value is used. The
    ``ram`` should also be rounded to power of two as ``vram``. There is also
@@ -6365,6 +6399,12 @@ Serial port
        <source path='/dev/pts/3'/>
        <target port='0'/>
      </serial>
+     <!-- Debug port for SeaBIOS / EDK II -->
+     <serial type='pty'>
+       <target type='isa-debug'/>
+       <address type='isa' iobase='0x402'/>
+     </console>
+
    </devices>
    ...
 
@@ -6388,8 +6428,9 @@ values are, :since:`since 1.0.2` , ``isa-serial`` (usable with x86 guests),
 ``usb-serial`` (usable whenever USB support is available) and ``pci-serial``
 (usable whenever PCI support is available); :since:`since 3.10.0` ,
 ``spapr-vio-serial`` (usable with ppc64/pseries guests), ``system-serial``
-(usable with aarch64/virt and, :since:`since 4.7.0` , riscv/virt guests) and
+(usable with aarch64/virt and, :since:`since 4.7.0` , riscv/virt guests),
-``sclp-serial`` (usable with s390 and s390x guests) are available as well.
+``sclp-serial`` (usable with s390 and s390x guests) are available as well
+and :since:`since 8.1.0` ``isa-debug`` (usable with x86 guests).
 
 :since:`Since 3.10.0` , the ``target`` element can have an optional ``model``
 subelement; valid values for its ``name`` attribute are: ``isa-serial`` (usable
@@ -6398,9 +6439,12 @@ with the ``isa-serial`` target type); ``usb-serial`` (usable with the
 target type); ``spapr-vty`` (usable with the ``spapr-vio-serial`` target type);
 ``pl011`` and, :since:`since 4.7.0` , ``16550a`` (usable with the
 ``system-serial`` target type); ``sclpconsole`` and ``sclplmconsole`` (usable
-with the ``sclp-serial`` target type). Providing a target model is usually
+with the ``sclp-serial`` target type). ``isa-debugcon`` (usable with the
-unnecessary: libvirt will automatically pick one that's suitable for the chosen
+``isa-debug`` target type); provides a virtual console for receiving debug
-target type, and overriding that value is generally not recommended.
+messages from the firmware on x86 platforms. :since:`Since: 8.1.0`.
+Providing a target model is usually unnecessary: libvirt will automatically
+pick one that's suitable for the chosen target type, and overriding that
+value is generally not recommended.
 
 If any of the attributes is not specified by the user, libvirt will choose a
 value suitable for most users.
@@ -7079,6 +7123,20 @@ is permitted with the following attributes.
   The audio format, one of ``s8``, ``u8``, ``s16``, ``u16``,
   ``s32``, ``u32``, ``f32``. The default is hypervisor specific.
 
+Note:
+If no ``<audio/>`` element is defined, and the ``graphics`` element is set to
+either 'vnc' or 'sdl', the libvirtd or virtqemud process will honor the following
+environment variables:
+
+* ``SDL_AUDIODRIVER``
+
+  Valid values are 'pulseaudio', 'esd', 'alsa' or 'arts'.
+
+* ``QEMU_AUDIO_DRV``
+
+  Valid values are 'pa', 'none', 'alsa', 'coreaudio', 'jack', 'oss',
+  'sdl', 'spice' or 'wav'.
+
 None audio backend
 ^^^^^^^^^^^^^^^^^^
 

docs/formatnetwork.html.in

@@ -1250,7 +1250,6 @@
     </dhcp>
   </ip>
   <ip family="ipv6" address="fdXX:XXXX:XXXX:NNNN:: prefix="64"/>
-  </ip>
 &lt;/network&gt;</pre>
 
     <p>IPv6 NAT addressing has some caveats over the more straight

docs/formatsecret.html.in

@@ -1,414 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Secret XML format</h1>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="SecretAttributes">Secret XML</a></h2>
-
-    <p>
-      Secrets stored by libvirt may have attributes associated with them, using
-      the <code>secret</code> element.  The <code>secret</code> element has two
-      optional attributes, each with values '<code>yes</code>' and
-      '<code>no</code>', and defaulting to '<code>no</code>':
-    </p>
-    <dl>
-      <dt><code>ephemeral</code></dt>
-      <dd>This secret must only be kept in memory, never stored persistently.
-      </dd>
-      <dt><code>private</code></dt>
-      <dd>The value of the secret must not be revealed to any caller of libvirt,
-        nor to any other node.
-      </dd>
-    </dl>
-    <p>
-      The top-level <code>secret</code> element may contain the following
-      elements:
-    </p>
-    <dl>
-      <dt><code>uuid</code></dt>
-      <dd>
-        An unique identifier for this secret (not necessarily in the UUID
-        format).  If omitted when defining a new secret, a random UUID is
-        generated.
-      </dd>
-      <dt><code>description</code></dt>
-      <dd>A human-readable description of the purpose of the secret.
-      </dd>
-      <dt><code>usage</code></dt>
-      <dd>
-        Specifies what this secret is used for.  A mandatory
-        <code>type</code> attribute specifies the usage category, currently
-        only <code>volume</code>, <code>ceph</code>, <code>iscsi</code>,
-        <code>tls</code>, and <code>vtpm</code> are defined. Specific usage
-        categories are described below.
-      </dd>
-    </dl>
-
-    <h3><a id="VolumeUsageType">Usage type "volume"</a></h3>
-
-    <p>
-      This secret is associated with a volume, whether the format is either
-      for a "luks" encrypted volume. Each volume will have a
-      unique secret associated with it and it is safe to delete the
-      secret after the volume is deleted. The
-      <code>&lt;usage type='volume'&gt;</code> element must contain a
-      single <code>volume</code> element that specifies the path of the volume
-      this secret is associated with. For example, create a volume-secret.xml
-      file as follows:
-    </p>
-
-    <pre>
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;Super secret name of my first puppy&lt;/description&gt;
-   &lt;uuid&gt;0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f&lt;/uuid&gt;
-   &lt;usage type='volume'&gt;
-      &lt;volume&gt;/var/lib/libvirt/images/puppyname.img&lt;/volume&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-    </pre>
-
-    <p>
-      Define the secret and set the passphrase as follows:
-    </p>
-    <pre>
-# virsh secret-define volume-secret.xml
-Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
-    </pre>
-
-    <p>
-      See <a href="#settingSecrets">virsh secret-set-value</a> on how
-      to set the value of the secret.
-    </p>
-
-    <p>
-      The volume type secret can be supplied either in volume XML during
-      creation of a <a href="formatstorage.html#StorageVol">storage volume</a>
-      in order to provide the passphrase to encrypt the volume or in
-      domain XML <a href="formatdomain.html#elementsDisks">disk device</a>
-      in order to provide the passphrase to decrypt the volume,
-      <span class="since">since 2.1.0</span>. An example follows:
-    </p>
-    <pre>
-# cat luks-secret.xml
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;LUKS Sample Secret&lt;/description&gt;
-   &lt;uuid&gt;f52a81b2-424e-490c-823d-6bd4235bc57&lt;/uuid&gt;
-   &lt;usage type='volume'&gt;
-      &lt;volume&gt;/var/lib/libvirt/images/luks-sample.img&lt;/volume&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-
-# virsh secret-define luks-secret.xml
-Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
-    </pre>
-    <p>
-      See <a href="#settingSecrets">virsh secret-set-value</a> on how
-      to set the value of the secret.
-    </p>
-
-    <p>
-      The volume type secret can be supplied in domain XML for a luks storage
-      volume <a href="formatstorageencryption.html">encryption</a> as follows:
-    </p>
-    <pre>
-&lt;encryption format='luks'&gt;
-  &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/&gt;
-&lt;/encryption&gt;
-    </pre>
-
-    <h3><a id="CephUsageType">Usage type "ceph"</a></h3>
-    <p>
-      This secret is associated with a Ceph RBD (rados block device).
-      The <code>&lt;usage type='ceph'&gt;</code> element must contain
-      a single <code>name</code> element that specifies a usage name
-      for the secret.  The Ceph secret can then be used by UUID or by
-      this usage name via the <code>&lt;auth&gt;</code> element of
-      a <a href="formatdomain.html#elementsDisks">disk device</a> or
-      a <a href="formatstorage.html">storage pool (rbd)</a>.
-      <span class="since">Since 0.9.7</span>. The following is an example
-      of the steps to be taken.  First create a ceph-secret.xml file:
-    </p>
-
-    <pre>
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;CEPH passphrase example&lt;/description&gt;
-   &lt;usage type='ceph'&gt;
-      &lt;name&gt;ceph_example&lt;/name&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-    </pre>
-
-    <p>
-      Next, use <code>virsh secret-define ceph-secret.xml</code> to define
-      the secret and <code>virsh secret-set-value</code> using the generated
-      UUID value and a base64 generated secret value in order to define the
-      chosen secret pass phrase.
-    </p>
-    <pre>
-# virsh secret-define ceph-secret.xml
-Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created
-#
-# virsh secret-list
- UUID                                 Usage
------------------------------------------------------------
- 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
-    </pre>
-    <p>
-      See <a href="#settingSecrets">virsh secret-set-value</a> on how
-      to set the value of the secret.
-    </p>
-
-    <p>
-      The ceph secret can then be used by UUID or by the
-      usage name via the <code>&lt;auth&gt;</code> element in a domain's
-      <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
-      element as follows:
-    </p>
-    <pre>
-&lt;auth username='myname'&gt;
-  &lt;secret type='ceph' usage='ceph_example'/&gt;
-&lt;/auth&gt;
-    </pre>
-
-    <p>
-      As well as the <code>&lt;auth&gt;</code> element in a
-      <a href="formatstorage.html">storage pool (rbd)</a>
-      <code>&lt;source&gt;</code> element as follows:
-    </p>
-    <pre>
-&lt;auth type='ceph' username='myname'&gt;
-  &lt;secret usage='ceph_example'/&gt;
-&lt;/auth&gt;
-    </pre>
-
-    <h3><a id="iSCSIUsageType">Usage type "iscsi"</a></h3>
-
-    <p>
-      This secret is associated with an iSCSI target for CHAP authentication.
-      The <code>&lt;usage type='iscsi'&gt;</code> element must contain
-      a single <code>target</code> element that specifies a usage name
-      for the secret. The iSCSI secret can then be used by UUID or by
-      this usage name via the <code>&lt;auth&gt;</code> element of
-      a <a href="formatdomain.html#elementsDisks">disk device</a> or
-      a <a href="formatstorage.html">storage pool (iscsi)</a>.
-      <span class="since">Since 1.0.4</span>. The following is an example
-      of the XML that may be used to generate a secret for iSCSI CHAP
-      authentication. Assume the following sample entry in an iSCSI
-      authentication file:
-    </p>
-      <pre>
-&lt;target iqn.2013-07.com.example:iscsi-pool&gt;
-backing-store /home/tgtd/iscsi-pool/disk1
-backing-store /home/tgtd/iscsi-pool/disk2
-incominguser myname mysecret
-&lt;/target&gt;
-      </pre>
-    <p>
-      Define an iscsi-secret.xml file to describe the secret. Use the
-      <code>incominguser</code> username used in your iSCSI authentication
-      configuration file as the value for the <code>username</code> attribute.
-      The <code>description</code> attribute should contain configuration
-      specific data. The <code>target</code> name may be any name of your
-      choosing to be used as the <code>usage</code> when used in the pool
-      or disk XML description.
-    </p>
-    <pre>
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;Passphrase for the iSCSI example.com server&lt;/description&gt;
-   &lt;usage type='iscsi'&gt;
-      &lt;target&gt;libvirtiscsi&lt;/target&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-    </pre>
-
-    <p>
-      Next, use <code>virsh secret-define iscsi-secret.xml</code> to define
-      the secret and
-      <code><a href="#settingSecrets">virsh secret-set-value</a></code>
-      using the generated
-      UUID value and a base64 generated secret value in order to define the
-      chosen secret pass phrase.  The pass phrase must match the password
-      used in the iSCSI authentication configuration file.
-    </p>
-    <pre>
-# virsh secret-define secret.xml
-Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
-
-# virsh secret-list
- UUID                                 Usage
------------------------------------------------------------
- c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi
-
-    </pre>
-
-    <p>
-      See <a href="#settingSecrets">virsh secret-set-value</a> on how
-      to set the value of the secret.
-    </p>
-
-    <p>
-      The iSCSI secret can then be used by UUID or by the
-      usage name via the <code>&lt;auth&gt;</code> element in a domain's
-      <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
-      element as follows:
-    </p>
-    <pre>
-&lt;auth username='myname'&gt;
-  &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
-&lt;/auth&gt;
-    </pre>
-
-    <p>
-      As well as the <code>&lt;auth&gt;</code> element in a
-      <a href="formatstorage.html">storage pool (iscsi)</a>
-      <code>&lt;source&gt;</code> element as follows:
-    </p>
-    <pre>
-&lt;auth type='chap' username='myname'&gt;
-  &lt;secret usage='libvirtiscsi'/&gt;
-&lt;/auth&gt;
-    </pre>
-
-    <h3><a id="tlsUsageType">Usage type "tls"</a></h3>
-
-    <p>
-      This secret may be used in order to provide the passphrase for the
-      private key used to provide TLS credentials.
-      The <code>&lt;usage type='tls'&gt;</code> element must contain a
-      single <code>name</code> element that specifies a usage name
-      for the secret.
-      <span class="since">Since 2.3.0</span>.
-      The following is an example of the expected XML and processing to
-      define the secret:
-    </p>
-
-    <pre>
-# cat tls-secret.xml
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;sample tls secret&lt;/description&gt;
-   &lt;usage type='tls'&gt;
-      &lt;name&gt;TLS_example&lt;/name&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-
-# virsh secret-define tls-secret.xml
-Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
-
-# virsh secret-list
- UUID                                 Usage
------------------------------------------------------------
- 718c71bd-67b5-4a2b-87ec-a24e8ca200dc  tls TLS_example
-#
-
-    </pre>
-
-    <p>
-      A secret may also be defined via the
-      <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
-       <code>virSecretDefineXML</code></a> API.
-
-      Once the secret is defined, a secret value will need to be set. The
-      secret would be the passphrase used to access the TLS credentials.
-      The following is a simple example of using
-      <code><a href="#settingSecrets">virsh secret-set-value</a></code> to set
-      the secret value. The
-      <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
-      <code>virSecretSetValue</code></a> API may also be used to set
-      a more secure secret without using printable/readable characters.
-    </p>
-
-    <h3><a id="vTPMUsageType">Usage type "vtpm"</a></h3>
-
-    <p>
-      This secret is associated with a virtualized TPM (vTPM) and serves
-      as a passphrase for deriving a key from for encrypting the state
-      of the vTPM.
-      The <code>&lt;usage type='vtpm'&gt;</code> element must contain
-      a single <code>name</code> element that specifies a usage name
-      for the secret.  The vTPM secret can then be used by UUID
-      via the <code>&lt;encryption&gt;</code> element of
-      a <a href="formatdomain.html#elementsTpm">tpm</a> when using an
-      emulator.
-      <span class="since">Since 5.6.0</span>. The following is an example
-      of the steps to be taken.  First create a vtpm-secret.xml file:    </p>
-
-    <pre>
-# cat vtpm-secret.xml
-&lt;secret ephemeral='no' private='yes'&gt;
-   &lt;description&gt;sample vTPM secret&lt;/description&gt;
-   &lt;usage type='vtpm'&gt;
-      &lt;name&gt;VTPM_example&lt;/name&gt;
-   &lt;/usage&gt;
-&lt;/secret&gt;
-
-# virsh secret-define vtpm-secret.xml
-Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created
-
-# virsh secret-list
- UUID                                   Usage
-----------------------------------------------------------------------------------------
- 6dd3e4a5-1d76-44ce-961f-f119f5aad935   vtpm VTPM_example
-
-#
-
-    </pre>
-
-    <p>
-      A secret may also be defined via the
-      <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
-       <code>virSecretDefineXML</code></a> API.
-
-      Once the secret is defined, a secret value will need to be set. The
-      secret would be the passphrase used to decrypt the vTPM state.
-      The following is a simple example of using
-      <code><a href="#settingSecrets">virsh secret-set-value</a></code>
-      to set the secret value. The
-      <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
-      <code>virSecretSetValue</code></a> API may also be used to set
-      a more secure secret without using printable/readable characters.
-    </p>
-
-    <h2><a id="settingSecrets">Setting secret values in virsh</a></h2>
-
-    <p>
-      To set the value of the secret you can use the following virsh commands.
-      If the secret is a password-like string (printable characters, no newline)
-      you can use:
-    </p>
-    <pre>
-# virsh secret-set-value --interactive 6dd3e4a5-1d76-44ce-961f-f119f5aad935
-Enter new value for secret:
-Secret value set
-    </pre>
-
-    <p>
-      Another secure option is to read the secret from a file. This way the
-      secret can contain any bytes (even NUL and non-printable characters). The
-      length of the secret is the length of the input file. Alternatively the
-      <code>--plain</code> option can be omitted if the file contents are
-      base64-encoded.
-    </p>
-
-    <pre>
-# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file --plain secretinfile
-Secret value set
-    </pre>
-
-    <p>
-      <b>WARNING</b> The following approach is <b>insecure</b> and deprecated.
-      The secret can also be set via an argument. Note that other users may see
-      the actual secret in the process listing!
-      The secret must be base64 encoded.
-    </p>
-
-    <pre>
-# MYSECRET=`printf %s "open sesame" | base64`
-# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET
-Secret value set
-    </pre>
-
-  </body>
-</html>

docs/formatsecret.rst

@@ -0,0 +1,332 @@
+.. role:: since
+
+=================
+Secret XML format
+=================
+
+.. contents::
+
+Secret XML
+----------
+
+Secrets stored by libvirt may have attributes associated with them, using the
+``secret`` element. The ``secret`` element has two optional attributes, each
+with values '``yes``' and '``no``', and defaulting to '``no``':
+
+``ephemeral``
+   This secret must only be kept in memory, never stored persistently.
+``private``
+   The value of the secret must not be revealed to any caller of libvirt, nor to
+   any other node.
+
+The top-level ``secret`` element may contain the following elements:
+
+``uuid``
+   An unique identifier for this secret (not necessarily in the UUID format). If
+   omitted when defining a new secret, a random UUID is generated.
+``description``
+   A human-readable description of the purpose of the secret.
+``usage``
+   Specifies what this secret is used for. A mandatory ``type`` attribute
+   specifies the usage category, currently only ``volume``, ``ceph``, ``iscsi``,
+   ``tls``, and ``vtpm`` are defined. Specific usage categories are described
+   below.
+
+Usage type "volume"
+~~~~~~~~~~~~~~~~~~~
+
+This secret is associated with a volume, whether the format is either for a
+"luks" encrypted volume. Each volume will have a unique secret associated with
+it and it is safe to delete the secret after the volume is deleted. The
+``<usage type='volume'>`` element must contain a single ``volume`` element that
+specifies the path of the volume this secret is associated with. For example,
+create a volume-secret.xml file as follows:
+
+::
+
+   <secret ephemeral='no' private='yes'>
+      <description>Super secret name of my first puppy</description>
+      <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid>
+      <usage type='volume'>
+         <volume>/var/lib/libvirt/images/puppyname.img</volume>
+      </usage>
+   </secret>
+
+Define the secret and set the passphrase as follows:
+
+::
+
+   # virsh secret-define volume-secret.xml
+   Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
+
+See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the
+secret.
+
+The volume type secret can be supplied either in volume XML during creation of a
+`storage volume <formatstorage.html#StorageVol>`__ in order to provide the
+passphrase to encrypt the volume or in domain XML `disk
+device <formatdomain.html#elementsDisks>`__ in order to provide the passphrase
+to decrypt the volume, :since:`since 2.1.0` . An example follows:
+
+::
+
+   # cat luks-secret.xml
+   <secret ephemeral='no' private='yes'>
+      <description>LUKS Sample Secret</description>
+      <uuid>f52a81b2-424e-490c-823d-6bd4235bc57</uuid>
+      <usage type='volume'>
+         <volume>/var/lib/libvirt/images/luks-sample.img</volume>
+      </usage>
+   </secret>
+
+   # virsh secret-define luks-secret.xml
+   Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
+
+See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the
+secret.
+
+The volume type secret can be supplied in domain XML for a luks storage volume
+`encryption <formatstorageencryption.html>`__ as follows:
+
+::
+
+   <encryption format='luks'>
+     <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/>
+   </encryption>
+
+Usage type "ceph"
+~~~~~~~~~~~~~~~~~
+
+This secret is associated with a Ceph RBD (rados block device). The
+``<usage type='ceph'>`` element must contain a single ``name`` element that
+specifies a usage name for the secret. The Ceph secret can then be used by UUID
+or by this usage name via the ``<auth>`` element of a `disk
+device <formatdomain.html#elementsDisks>`__ or a `storage pool
+(rbd) <formatstorage.html>`__. :since:`Since 0.9.7` . The following is an
+example of the steps to be taken. First create a ceph-secret.xml file:
+
+::
+
+   <secret ephemeral='no' private='yes'>
+      <description>CEPH passphrase example</description>
+      <usage type='ceph'>
+         <name>ceph_example</name>
+      </usage>
+   </secret>
+
+Next, use ``virsh secret-define ceph-secret.xml`` to define the secret and
+``virsh secret-set-value`` using the generated UUID value and a base64 generated
+secret value in order to define the chosen secret pass phrase.
+
+::
+
+   # virsh secret-define ceph-secret.xml
+   Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created
+   #
+   # virsh secret-list
+    UUID                                 Usage
+   -----------------------------------------------------------
+    1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
+
+See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the
+secret.
+
+The ceph secret can then be used by UUID or by the usage name via the ``<auth>``
+element in a domain's `<disk> <formatdomain.html#elementsDisks>`__ element as
+follows:
+
+::
+
+   <auth username='myname'>
+     <secret type='ceph' usage='ceph_example'/>
+   </auth>
+
+As well as the ``<auth>`` element in a `storage pool
+(rbd) <formatstorage.html>`__ ``<source>`` element as follows:
+
+::
+
+   <auth type='ceph' username='myname'>
+     <secret usage='ceph_example'/>
+   </auth>
+
+Usage type "iscsi"
+~~~~~~~~~~~~~~~~~~
+
+This secret is associated with an iSCSI target for CHAP authentication. The
+``<usage type='iscsi'>`` element must contain a single ``target`` element that
+specifies a usage name for the secret. The iSCSI secret can then be used by UUID
+or by this usage name via the ``<auth>`` element of a `disk
+device <formatdomain.html#elementsDisks>`__ or a `storage pool
+(iscsi) <formatstorage.html>`__. :since:`Since 1.0.4` . The following is an
+example of the XML that may be used to generate a secret for iSCSI CHAP
+authentication. Assume the following sample entry in an iSCSI authentication
+file:
+
+::
+
+   <target iqn.2013-07.com.example:iscsi-pool>
+   backing-store /home/tgtd/iscsi-pool/disk1
+   backing-store /home/tgtd/iscsi-pool/disk2
+   incominguser myname mysecret
+   </target>
+
+Define an iscsi-secret.xml file to describe the secret. Use the ``incominguser``
+username used in your iSCSI authentication configuration file as the value for
+the ``username`` attribute. The ``description`` attribute should contain
+configuration specific data. The ``target`` name may be any name of your
+choosing to be used as the ``usage`` when used in the pool or disk XML
+description.
+
+::
+
+   <secret ephemeral='no' private='yes'>
+      <description>Passphrase for the iSCSI example.com server</description>
+      <usage type='iscsi'>
+         <target>libvirtiscsi</target>
+      </usage>
+   </secret>
+
+Next, use ``virsh secret-define iscsi-secret.xml`` to define the secret and
+``virsh secret-set-value`` using the generated UUID value and a base64 generated
+secret value in order to define the chosen secret pass phrase. The pass phrase
+must match the password used in the iSCSI authentication configuration file.
+
+::
+
+   # virsh secret-define secret.xml
+   Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
+
+   # virsh secret-list
+    UUID                                 Usage
+   -----------------------------------------------------------
+    c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi
+
+
+See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the
+secret.
+
+The iSCSI secret can then be used by UUID or by the usage name via the
+``<auth>`` element in a domain's `<disk> <formatdomain.html#elementsDisks>`__
+element as follows:
+
+::
+
+   <auth username='myname'>
+     <secret type='iscsi' usage='libvirtiscsi'/>
+   </auth>
+
+As well as the ``<auth>`` element in a `storage pool
+(iscsi) <formatstorage.html>`__ ``<source>`` element as follows:
+
+::
+
+   <auth type='chap' username='myname'>
+     <secret usage='libvirtiscsi'/>
+   </auth>
+
+Usage type "tls"
+~~~~~~~~~~~~~~~~
+
+This secret may be used in order to provide the passphrase for the private key
+used to provide TLS credentials. The ``<usage type='tls'>`` element must contain
+a single ``name`` element that specifies a usage name for the secret.
+:since:`Since 2.3.0` . The following is an example of the expected XML and
+processing to define the secret:
+
+::
+
+   # cat tls-secret.xml
+   <secret ephemeral='no' private='yes'>
+      <description>sample tls secret</description>
+      <usage type='tls'>
+         <name>TLS_example</name>
+      </usage>
+   </secret>
+
+   # virsh secret-define tls-secret.xml
+   Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
+
+   # virsh secret-list
+    UUID                                 Usage
+   -----------------------------------------------------------
+    718c71bd-67b5-4a2b-87ec-a24e8ca200dc  tls TLS_example
+
+A secret may also be defined via the
+`virSecretDefineXML <html/libvirt-libvirt-secret.html#virSecretDefineXML>`__
+API. Once the secret is defined, a secret value will need to be set. The secret
+would be the passphrase used to access the TLS credentials. The following is a
+simple example of using ``virsh secret-set-value`` to set the secret value. The
+`virSecretSetValue <html/libvirt-libvirt-secret.html#virSecretSetValue>`__ API
+may also be used to set a more secure secret without using printable/readable
+characters.
+
+Usage type "vtpm"
+~~~~~~~~~~~~~~~~~
+
+This secret is associated with a virtualized TPM (vTPM) and serves as a
+passphrase for deriving a key from for encrypting the state of the vTPM. The
+``<usage type='vtpm'>`` element must contain a single ``name`` element that
+specifies a usage name for the secret. The vTPM secret can then be used by UUID
+via the ``<encryption>`` element of a `tpm <formatdomain.html#elementsTpm>`__
+when using an emulator. :since:`Since 5.6.0` . The following is an example of
+the steps to be taken. First create a vtpm-secret.xml file:
+
+::
+
+   # cat vtpm-secret.xml
+   <secret ephemeral='no' private='yes'>
+      <description>sample vTPM secret</description>
+      <usage type='vtpm'>
+         <name>VTPM_example</name>
+      </usage>
+   </secret>
+
+   # virsh secret-define vtpm-secret.xml
+   Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created
+
+   # virsh secret-list
+    UUID                                   Usage
+   ----------------------------------------------------------------------------------------
+    6dd3e4a5-1d76-44ce-961f-f119f5aad935   vtpm VTPM_example
+
+A secret may also be defined via the
+`virSecretDefineXML <html/libvirt-libvirt-secret.html#virSecretDefineXML>`__
+API. Once the secret is defined, a secret value will need to be set. The secret
+would be the passphrase used to decrypt the vTPM state. The following is a
+simple example of using ``virsh secret-set-value`` to set the secret value. The
+`virSecretSetValue <html/libvirt-libvirt-secret.html#virSecretSetValue>`__ API
+may also be used to set a more secure secret without using printable/readable
+characters.
+
+Setting secret values in virsh
+------------------------------
+
+To set the value of the secret you can use the following virsh commands. If the
+secret is a password-like string (printable characters, no newline) you can use:
+
+::
+
+   # virsh secret-set-value --interactive 6dd3e4a5-1d76-44ce-961f-f119f5aad935
+   Enter new value for secret:
+   Secret value set
+
+Another secure option is to read the secret from a file. This way the secret can
+contain any bytes (even NUL and non-printable characters). The length of the
+secret is the length of the input file. Alternatively the ``--plain`` option can
+be omitted if the file contents are base64-encoded.
+
+::
+
+   # virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file --plain secretinfile
+   Secret value set
+
+**WARNING** The following approach is **insecure** and deprecated. The secret
+can also be set via an argument. Note that other users may see the actual secret
+in the process listing! The secret must be base64 encoded.
+
+::
+
+   # MYSECRET=`printf %s "open sesame" | base64`
+   # virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET
+   Secret value set

docs/formatsnapshot.html.in

@@ -1,352 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Snapshot XML format</h1>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="SnapshotAttributes">Snapshot XML</a></h2>
-
-    <p>
-      Snapshots are one form
-      of <a href="kbase/domainstatecapture.html">domain state
-      capture</a>.  There are several types of snapshots:
-    </p>
-    <dl>
-      <dt>disk snapshot</dt>
-      <dd>Contents of disks (whether a subset or all disks associated
-        with the domain) are saved at a given point of time, and can
-        be restored back to that state.  On a running guest, a disk
-        snapshot is likely to be only crash-consistent rather than
-        clean (that is, it represents the state of the disk on a
-        sudden power outage, and may need fsck or journal replays to
-        be made consistent); on an inactive guest, a disk snapshot is
-        clean if the disks were clean when the guest was last shut
-        down.  Disk snapshots exist in two forms: internal (file
-        formats such as qcow2 track both the snapshot and changes
-        since the snapshot in a single file) and external (the
-        snapshot is one file, and the changes since the snapshot are
-        in another file).</dd>
-      <dt>memory state (or VM state)</dt>
-      <dd>Tracks only the state of RAM and all other resources in use
-        by the VM.  If the disks are unmodified between the time a VM
-        state snapshot is taken and restored, then the guest will
-        resume in a consistent state; but if the disks are modified
-        externally in the meantime, this is likely to lead to data
-        corruption.</dd>
-      <dt>full system</dt>
-      <dd>A combination of disk snapshots for all disks as well as VM
-        memory state, which can be used to resume the guest from where it
-        left off with symptoms similar to hibernation (that is, TCP
-        connections in the guest may have timed out, but no files or
-        processes are lost).</dd>
-    </dl>
-
-    <p>
-      Libvirt can manage all three types of snapshots.  For now, VM
-      state (memory) snapshots are created only by
-      the <code>virDomainSave()</code>, <code>virDomainSaveFlags</code>,
-      and <code>virDomainManagedSave()</code> functions, and restored
-      via the <code>virDomainRestore()</code>,
-      <code>virDomainRestoreFlags()</code>, <code>virDomainCreate()</code>,
-      and <code>virDomainCreateWithFlags()</code> functions (as well
-      as via domain autostart).  With managed snapshots, libvirt
-      tracks all information internally; with save images, the user
-      tracks the snapshot file, but libvirt provides functions such
-      as <code>virDomainSaveImageGetXMLDesc()</code> to work with
-      those files.
-    </p>
-    <p>Full system snapshots are created
-      by <code>virDomainSnapshotCreateXML()</code> with no flags, while
-      disk snapshots are created by the same function with
-      the <code>VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY</code>
-      flag. Regardless of the flags provided, restoration of the
-      snapshot is handled by
-      the <code>virDomainRevertToSnapshot()</code> function.  For
-      these types of snapshots, libvirt tracks each snapshot as a
-      separate <code>virDomainSnapshotPtr</code> object, and maintains
-      a tree relationship of which snapshots descended from an earlier
-      point in time.
-    </p>
-
-    <p>
-      Attributes of libvirt snapshots are stored as child elements of
-      the <code>domainsnapshot</code> element.  At snapshot creation
-      time, normally only the <code>name</code>, <code>description</code>,
-      and <code>disks</code> elements are settable; the rest of the
-      fields are ignored on creation, and will be filled in by
-      libvirt in for informational purposes
-      by <code>virDomainSnapshotGetXMLDesc()</code>.  However, when
-      redefining a snapshot (<span class="since">since 0.9.5</span>),
-      with the <code>VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE</code> flag
-      of <code>virDomainSnapshotCreateXML()</code>, all of the XML
-      described here is relevant on input, even the fields that are
-      normally described as readonly for output.
-    </p>
-    <p>
-      Snapshots are maintained in a hierarchy.  A domain can have a
-      current snapshot, which is the most recent snapshot compared to
-      the current state of the domain (although a domain might have
-      snapshots without a current snapshot, if snapshots have been
-      deleted in the meantime).  Creating or reverting to a snapshot
-      sets that snapshot as current, and the prior current snapshot is
-      the parent of the new snapshot.  Branches in the hierarchy can
-      be formed by reverting to a snapshot with a child, then creating
-      another snapshot.  For now, the creation of external snapshots
-      when checkpoints exist is forbidden, although future work will
-      make it possible to integrate these two concepts.
-    </p>
-    <p>
-      The top-level <code>domainsnapshot</code> element may contain
-      the following elements:
-    </p>
-    <dl>
-      <dt><code>name</code></dt>
-      <dd>The optional name for this snapshot.  If the name is
-        omitted, libvirt will create a name based on the time of the
-        creation.
-      </dd>
-      <dt><code>description</code></dt>
-      <dd>An optional human-readable description of the snapshot.  If
-        the description is omitted when initially creating the
-        snapshot, then this field will be empty.
-      </dd>
-      <dt><code>memory</code></dt>
-      <dd>On input, this is an optional request for how to handle VM
-        memory state.  For an offline domain or a disk-only snapshot,
-        attribute <code>snapshot</code> must be <code>no</code>, since
-        there is no VM state saved; otherwise, the attribute can
-        be <code>internal</code> if the memory state is piggy-backed with
-        other internal disk state, or <code>external</code> along with
-        a second attribute <code>file</code> giving the absolute path
-        of the file holding the VM memory state.  <span class="since">Since
-        1.0.1</span>
-      </dd>
-      <dt><code>disks</code></dt>
-      <dd>On input, this is an optional listing of specific
-        instructions for disk snapshots; it is needed when making a
-        snapshot of only a subset of the disks associated with a
-        domain, or when overriding the domain defaults for how to
-        snapshot each disk, or for providing specific control over
-        what file name is created in an external snapshot.  On output,
-        this is fully populated to show the state of each disk in the
-        snapshot, including any properties that were generated by the
-        hypervisor defaults.  For full system snapshots, this field is
-        ignored on input and omitted on output (a full system snapshot
-        implies that all disks participate in the snapshot process).
-        This element has a list of <code>disk</code>
-        sub-elements, describing anywhere from zero to all of the
-        disks associated with the domain.  <span class="since">Since
-        0.9.5</span>
-        <dl>
-          <dt><code>disk</code></dt>
-          <dd>This sub-element describes the snapshot properties of a
-            specific disk.  The attribute <code>name</code> is
-            mandatory, and must match either the <code>&lt;target
-            dev='name'/&gt;</code> (recommended) or an unambiguous
-            <code>&lt;source file='name'/&gt;</code> of one of
-            the <a href="formatdomain.html#elementsDisks">disk
-            devices</a> specified for the domain at the time of the
-            snapshot.  The attribute <code>snapshot</code> is
-            optional, and the possible values are the same as the
-            <code>snapshot</code> attribute for
-             <a href="formatdomain.html#elementsDisks">disk devices</a>
-            (<code>no</code>, <code>internal</code>,
-            or <code>external</code>).  Some hypervisors like ESX
-            require that if specified, the snapshot mode must not
-            override any snapshot mode attached to the corresponding
-            domain disk, while others like qemu allow this field to
-            override the domain default.
-
-            <dl>
-              <dt><code>source</code></dt>
-              <dd>If the snapshot mode is external (whether specified
-              or inherited), then there is an optional sub-element
-              <code>source</code>, with an attribute <code>file</code>
-              giving the name of the new file.
-              If <code>source</code> is not
-              given and the disk is backed by a local image file (not
-              a block device or remote storage), a file name is
-              generated that consists of the existing file name
-              with anything after the trailing dot replaced by the
-              snapshot name.  Remember that with external
-              snapshots, the original file name becomes the read-only
-              snapshot, and the new file name contains the read-write
-              delta of all disk changes since the snapshot.
-              <p/>
-              The <code>source</code> element also may contain the
-              <code>seclabel</code> element (described in the
-              <a href="formatdomain.html#seclabel">domain XML documentation</a>)
-              which can be used to override the domain security labeling policy
-              for <code>source</code>.
-              </dd>
-              <dt><code>driver</code></dt>
-              <dd>An optional sub-element <code>driver</code>,
-              with an attribute <code>type</code> giving the driver type (such
-              as qcow2), of the new file created by the external
-              snapshot of the new file.
-
-              Optionally <code>metadata_cache</code> sub-element can be used
-              with same semantics as the identically named subelement of the
-              domain definition disk's driver.
-              </dd>
-              <dt><code>seclabel</code></dt>
-            </dl>
-
-            <span class="since">Since 1.2.2</span> the <code>disk</code> element
-            supports an optional attribute <code>type</code> if the
-            <code>snapshot</code> attribute is set to <code>external</code>.
-            This attribute specifies the snapshot target storage type and allows
-            to overwrite the default <code>file</code> type. The <code>type</code>
-            attribute along with the format of the <code>source</code>
-            sub-element is identical to the <code>source</code> element used in
-            domain disk definitions. See the
-            <a href="formatdomain.html#elementsDisks">disk devices</a> section
-            documentation for further information.
-
-            Libvirt currently supports the <code>type</code> element in the qemu
-            driver and supported values are <code>file</code>, <code>block</code>
-            and <code>network</code> with a protocol of <code>gluster</code>
-            <span class="since">(since 1.2.2)</span>.
-          </dd>
-        </dl>
-      </dd>
-      <dt><code>creationTime</code></dt>
-      <dd>A readonly representation of the time this snapshot was
-        created.  The time is specified in seconds since the Epoch,
-        UTC (i.e. Unix time).
-      </dd>
-      <dt><code>state</code></dt>
-      <dd>A readonly representation of the state of the domain at the
-        time this snapshot was taken.  If a full system snapshot was
-        created, then this is the state of the domain at that
-        time. When the domain is reverted to this snapshot, the
-        domain's state will default to this state, unless overridden
-        by <code>virDomainRevertToSnapshot()</code> flags to revert to
-        a running or paused state. Additionally, this field can be the
-        value "disk-snapshot" (<span class="since">since 0.9.5</span>)
-        when it represents only a disk snapshot (no VM memory state),
-        and reverting to this snapshot will default to an inactive
-        guest.
-      </dd>
-      <dt><code>parent</code></dt>
-      <dd>Readonly, present only if this snapshot has a parent. The
-        parent name is given by the sub-element <code>name</code>. The
-        parent relationship allows tracking a tree of related snapshots.
-      </dd>
-      <dt><code>domain</code></dt>
-      <dd>A readonly representation of the domain that this snapshot
-        was taken against.  Older versions of libvirt stored only a
-        single child element, uuid; reverting to a snapshot like this
-        is risky if the current state of the domain differs from the
-        state that the domain was created in, and requires the use of
-        the <code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag
-        in <code>virDomainRevertToSnapshot()</code>.  Newer versions
-        of libvirt (<span class="since">since 0.9.5</span>) store the
-        entire inactive <a href="formatdomain.html">domain
-        configuration</a> at the time of the snapshot
-        (<span class="since">since 0.9.5</span>). The domain will have
-        security-sensitive information omitted
-        unless the flag <code>VIR_DOMAIN_SNAPSHOT_XML_SECURE</code> is
-        provided on a read-write connection.
-      </dd>
-      <dt><code>cookie</code></dt>
-      <dd>An optional readonly representation of a save image cookie
-        containing additional data libvirt may need to properly
-        restore a domain from an active snapshot when such data cannot
-        be stored directly in the <code>domain</code> to maintain
-        compatibility with older libvirt or hypervisor.
-      </dd>
-    </dl>
-
-    <h2><a id="example">Examples</a></h2>
-
-    <p>Using this XML to create a disk snapshot of just vda on a qemu
-      domain with two disks:</p>
-    <pre>
-&lt;domainsnapshot&gt;
-  &lt;description&gt;Snapshot of OS install and updates&lt;/description&gt;
-  &lt;disks&gt;
-    &lt;disk name='vda'&gt;
-      &lt;source file='/path/to/new'/&gt;
-    &lt;/disk&gt;
-    &lt;disk name='vdb' snapshot='no'/&gt;
-    &lt;disk name='vdc'&gt;
-      &lt;source file='/path/to/newc'&gt;
-        &lt;seclabel model='dac' relabel='no'/&gt;
-      &lt;/source&gt;
-    &lt;/disk&gt;
-  &lt;/disks&gt;
-&lt;/domainsnapshot&gt;</pre>
-
-    <p>will result in XML similar to this from
-      <code>virDomainSnapshotGetXMLDesc()</code>:</p>
-    <pre>
-&lt;domainsnapshot&gt;
-  &lt;name&gt;1270477159&lt;/name&gt;
-  &lt;description&gt;Snapshot of OS install and updates&lt;/description&gt;
-  &lt;state&gt;running&lt;/state&gt;
-  &lt;creationTime&gt;1270477159&lt;/creationTime&gt;
-  &lt;parent&gt;
-    &lt;name&gt;bare-os-install&lt;/name&gt;
-  &lt;/parent&gt;
-  &lt;memory snapshot='no'/&gt;
-  &lt;disks&gt;
-    &lt;disk name='vda' snapshot='external'&gt;
-      &lt;driver type='qcow2'/&gt;
-      <b>&lt;source file='/path/to/new'/&gt;</b>
-    &lt;/disk&gt;
-    &lt;disk name='vdb' snapshot='no'/&gt;
-  &lt;/disks&gt;
-  &lt;domain&gt;
-    &lt;name&gt;fedora&lt;/name&gt;
-    &lt;uuid&gt;93a5c045-6457-2c09-e56c-927cdf34e178&lt;/uuid&gt;
-    &lt;memory&gt;1048576&lt;/memory&gt;
-    ...
-    &lt;devices&gt;
-      &lt;disk type='file' device='disk'&gt;
-        &lt;driver name='qemu' type='raw'/&gt;
-        <b>&lt;source file='/path/to/old'/&gt;</b>
-        &lt;target dev='vda' bus='virtio'/&gt;
-      &lt;/disk&gt;
-      &lt;disk type='file' device='disk' snapshot='external'&gt;
-        &lt;driver name='qemu' type='raw'/&gt;
-        &lt;source file='/path/to/old2'/&gt;
-        &lt;target dev='vdb' bus='virtio'/&gt;
-      &lt;/disk&gt;
-      ...
-    &lt;/devices&gt;
-  &lt;/domain&gt;
-&lt;/domainsnapshot&gt;</pre>
-
-    <p>With that snapshot created, <code>/path/to/old</code> is the
-      read-only backing file to the new active
-      file <code>/path/to/new</code>.  The <code>&lt;domain&gt;</code>
-      element within the snapshot xml records the state of the domain
-      just before the snapshot; a call
-      to <code>virDomainGetXMLDesc()</code> will show that the domain
-      has been changed to reflect the snapshot:
-    </p>
-    <pre>
-&lt;domain&gt;
-  &lt;name&gt;fedora&lt;/name&gt;
-  &lt;uuid&gt;93a5c045-6457-2c09-e56c-927cdf34e178&lt;/uuid&gt;
-  &lt;memory&gt;1048576&lt;/memory&gt;
-  ...
-  &lt;devices&gt;
-    &lt;disk type='file' device='disk'&gt;
-      &lt;driver name='qemu' type='qcow2'/&gt;
-      <b>&lt;source file='/path/to/new'/&gt;</b>
-      &lt;target dev='vda' bus='virtio'/&gt;
-    &lt;/disk&gt;
-    &lt;disk type='file' device='disk' snapshot='external'&gt;
-      &lt;driver name='qemu' type='raw'/&gt;
-      &lt;source file='/path/to/old2'/&gt;
-      &lt;target dev='vdb' bus='virtio'/&gt;
-    &lt;/disk&gt;
-    ...
-  &lt;/devices&gt;
-&lt;/domain&gt;</pre>
-  </body>
-</html>

docs/formatsnapshot.rst

@@ -0,0 +1,304 @@
+.. role:: since
+
+===================
+Snapshot XML format
+===================
+
+.. contents::
+
+Snapshot XML
+------------
+
+Snapshots are one form of `domain state
+capture <kbase/domainstatecapture.html>`__. There are several types of
+snapshots:
+
+disk snapshot
+   Contents of disks (whether a subset or all disks associated with the domain)
+   are saved at a given point of time, and can be restored back to that state.
+   On a running guest, a disk snapshot is likely to be only crash-consistent
+   rather than clean (that is, it represents the state of the disk on a sudden
+   power outage, and may need fsck or journal replays to be made consistent); on
+   an inactive guest, a disk snapshot is clean if the disks were clean when the
+   guest was last shut down. Disk snapshots exist in two forms: internal (file
+   formats such as qcow2 track both the snapshot and changes since the snapshot
+   in a single file) and external (the snapshot is one file, and the changes
+   since the snapshot are in another file).
+memory state (or VM state)
+   Tracks only the state of RAM and all other resources in use by the VM. If the
+   disks are unmodified between the time a VM state snapshot is taken and
+   restored, then the guest will resume in a consistent state; but if the disks
+   are modified externally in the meantime, this is likely to lead to data
+   corruption.
+full system
+   A combination of disk snapshots for all disks as well as VM memory state,
+   which can be used to resume the guest from where it left off with symptoms
+   similar to hibernation (that is, TCP connections in the guest may have timed
+   out, but no files or processes are lost).
+
+Libvirt can manage all three types of snapshots. For now, VM state (memory)
+snapshots are created only by the ``virDomainSave()``, ``virDomainSaveFlags``,
+and ``virDomainManagedSave()`` functions, and restored via the
+``virDomainRestore()``, ``virDomainRestoreFlags()``, ``virDomainCreate()``, and
+``virDomainCreateWithFlags()`` functions (as well as via domain autostart). With
+managed snapshots, libvirt tracks all information internally; with save images,
+the user tracks the snapshot file, but libvirt provides functions such as
+``virDomainSaveImageGetXMLDesc()`` to work with those files.
+
+Full system snapshots are created by ``virDomainSnapshotCreateXML()`` with no
+flags, while disk snapshots are created by the same function with the
+``VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY`` flag. Regardless of the flags provided,
+restoration of the snapshot is handled by the ``virDomainRevertToSnapshot()``
+function. For these types of snapshots, libvirt tracks each snapshot as a
+separate ``virDomainSnapshotPtr`` object, and maintains a tree relationship of
+which snapshots descended from an earlier point in time.
+
+Attributes of libvirt snapshots are stored as child elements of the
+``domainsnapshot`` element. At snapshot creation time, normally only the
+``name``, ``description``, and ``disks`` elements are settable; the rest of the
+fields are ignored on creation, and will be filled in by libvirt in for
+informational purposes by ``virDomainSnapshotGetXMLDesc()``. However, when
+redefining a snapshot ( :since:`since 0.9.5` ), with the
+``VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE`` flag of
+``virDomainSnapshotCreateXML()``, all of the XML described here is relevant on
+input, even the fields that are normally described as readonly for output.
+
+Snapshots are maintained in a hierarchy. A domain can have a current snapshot,
+which is the most recent snapshot compared to the current state of the domain
+(although a domain might have snapshots without a current snapshot, if snapshots
+have been deleted in the meantime). Creating or reverting to a snapshot sets
+that snapshot as current, and the prior current snapshot is the parent of the
+new snapshot. Branches in the hierarchy can be formed by reverting to a snapshot
+with a child, then creating another snapshot. For now, the creation of external
+snapshots when checkpoints exist is forbidden, although future work will make it
+possible to integrate these two concepts.
+
+The top-level ``domainsnapshot`` element may contain the following elements:
+
+``name``
+
+   The optional name for this snapshot. If the name is omitted, libvirt will
+   create a name based on the time of the creation.
+
+``description``
+
+   An optional human-readable description of the snapshot. If the description
+   is omitted when initially creating the snapshot, then this field will be
+   empty.
+
+``memory``
+
+   On input, this is an optional request for how to handle VM memory state. For
+   an offline domain or a disk-only snapshot, attribute ``snapshot`` must be
+   ``no``, since there is no VM state saved; otherwise, the attribute can be
+   ``internal`` if the memory state is piggy-backed with other internal disk
+   state, or ``external`` along with a second attribute ``file`` giving the
+   absolute path of the file holding the VM memory state. :since:`Since 1.0.1`
+
+``disks``
+
+   On input, this is an optional listing of specific instructions for disk
+   snapshots; it is needed when making a snapshot of only a subset of the disks
+   associated with a domain, or when overriding the domain defaults for how to
+   snapshot each disk, or for providing specific control over what file name is
+   created in an external snapshot. On output, this is fully populated to show
+   the state of each disk in the snapshot, including any properties that were
+   generated by the hypervisor defaults. For full system snapshots, this field
+   is ignored on input and omitted on output (a full system snapshot implies
+   that all disks participate in the snapshot process). This element has a list
+   of ``disk`` sub-elements, describing anywhere from zero to all of the disks
+   associated with the domain. :since:`Since 0.9.5`
+
+   ``disk``
+
+      This sub-element describes the snapshot properties of a specific disk.
+      The attribute ``name`` is mandatory, and must match either the ``<target
+      dev='name'/>`` (recommended) or an unambiguous ``<source file='name'/>``
+      of one of the `disk devices <formatdomain.html#elementsDisks>`__
+      specified for the domain at the time of the snapshot. The attribute
+      ``snapshot`` is optional, and the possible values are the same as the
+      ``snapshot`` attribute for `disk devices
+      <formatdomain.html#elementsDisks>`__ (``no``, ``internal``, or
+      ``external``). Some hypervisors like ESX require that if specified, the
+      snapshot mode must not override any snapshot mode attached to the
+      corresponding domain disk, while others like qemu allow this field to
+      override the domain default.
+
+      :since:`Since 8.2.0` the ``snapshot`` attribute supports the ``manual``
+      value which instructs the hypervisor to create the snapshot and keep a
+      synchronized state by pausing the VM which allows to snapshot disk
+      storage from outside of the hypervisor if the storage provider supports
+      it.  The caller is responsible for resuming a VM paused by requesting a
+      ``manual`` snapshot. When reverting such snapshot, the expectation is that
+      the storage is configured in a way where the hypervisor will see the
+      correct image state.
+
+      :since:`Since 1.2.2` the ``disk`` element supports an optional attribute
+      ``type`` if the ``snapshot`` attribute is set to ``external``. This
+      attribute specifies the snapshot target storage type and allows to
+      overwrite the default ``file`` type. The ``type`` attribute along with
+      the format of the ``source`` sub-element is identical to the ``source``
+      element used in domain disk definitions. See the `disk devices
+      <formatdomain.html#elementsDisks>`__ section documentation for further
+      information. Libvirt currently supports the ``type`` element in the qemu
+      driver and supported values are ``file``, ``block`` and ``network``
+      :since:`(since 1.2.2)`.
+
+      ``source``
+
+         If the snapshot mode is external (whether specified or inherited),
+         then there is an optional sub-element ``source``, with an attribute
+         ``file`` giving the name of the new file. If ``source`` is not given
+         and the disk is backed by a local image file (not a block device or
+         remote storage), a file name is generated that consists of the
+         existing file name with anything after the trailing dot replaced by
+         the snapshot name. Remember that with external snapshots, the original
+         file name becomes the read-only snapshot, and the new file name
+         contains the read-write delta of all disk changes since the snapshot.
+
+         The ``source`` element also may contain the ``seclabel`` element
+         (described in the `domain XML documentation
+         <formatdomain.html#seclabel>`__) which can be used to override the
+         domain security labeling policy for ``source``.
+
+      ``driver``
+
+         An optional sub-element ``driver``, with an attribute ``type`` giving
+         the driver type (such as qcow2), of the new file created by the
+         external snapshot of the new file. Optionally ``metadata_cache``
+         sub-element can be used with same semantics as the identically named
+         subelement of the domain definition disk's driver.
+
+``creationTime``
+
+   A readonly representation of the time this snapshot was created. The time is
+   specified in seconds since the Epoch, UTC (i.e. Unix time).
+
+``state``
+
+   A readonly representation of the state of the domain at the time this
+   snapshot was taken. If a full system snapshot was created, then this is the
+   state of the domain at that time. When the domain is reverted to this
+   snapshot, the domain's state will default to this state, unless overridden
+   by ``virDomainRevertToSnapshot()`` flags to revert to a running or paused
+   state.  Additionally, this field can be the value "disk-snapshot" (
+   :since:`since 0.9.5`) when it represents only a disk snapshot (no VM memory
+   state), and reverting to this snapshot will default to an inactive guest.
+
+``parent``
+
+   Readonly, present only if this snapshot has a parent. The parent name is
+   given by the sub-element ``name``. The parent relationship allows tracking a
+   tree of related snapshots.
+
+``domain``
+
+   A readonly representation of the domain that this snapshot was taken
+   against.  Older versions of libvirt stored only a single child element,
+   uuid; reverting to a snapshot like this is risky if the current state of the
+   domain differs from the state that the domain was created in, and requires
+   the use of the ``VIR_DOMAIN_SNAPSHOT_REVERT_FORCE`` flag in
+   ``virDomainRevertToSnapshot()``.  Newer versions of libvirt ( :since:`since
+   0.9.5` ) store the entire inactive `domain configuration
+   <formatdomain.html>`__ at the time of the snapshot ( :since:`since 0.9.5` ).
+   The domain will have security-sensitive information omitted unless the flag
+   ``VIR_DOMAIN_SNAPSHOT_XML_SECURE`` is provided on a read-write connection.
+
+``cookie``
+
+   An optional readonly representation of a save image cookie containing
+   additional data libvirt may need to properly restore a domain from an active
+   snapshot when such data cannot be stored directly in the ``domain`` to
+   maintain compatibility with older libvirt or hypervisor.
+
+Examples
+--------
+
+Using this XML to create a disk snapshot of just vda on a qemu domain with two
+disks:
+
+::
+
+   <domainsnapshot>
+     <description>Snapshot of OS install and updates</description>
+     <disks>
+       <disk name='vda'>
+         <source file='/path/to/new'/>
+       </disk>
+       <disk name='vdb' snapshot='no'/>
+       <disk name='vdc'>
+         <source file='/path/to/newc'>
+           <seclabel model='dac' relabel='no'/>
+         </source>
+       </disk>
+     </disks>
+   </domainsnapshot>
+
+will result in XML similar to this from ``virDomainSnapshotGetXMLDesc()``:
+
+::
+
+   <domainsnapshot>
+     <name>1270477159</name>
+     <description>Snapshot of OS install and updates</description>
+     <state>running</state>
+     <creationTime>1270477159</creationTime>
+     <parent>
+       <name>bare-os-install</name>
+     </parent>
+     <memory snapshot='no'/>
+     <disks>
+       <disk name='vda' snapshot='external'>
+         <driver type='qcow2'/>
+         <source file='/path/to/new'/>
+       </disk>
+       <disk name='vdb' snapshot='no'/>
+     </disks>
+     <domain>
+       <name>fedora</name>
+       <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
+       <memory>1048576</memory>
+       ...
+       <devices>
+         <disk type='file' device='disk'>
+           <driver name='qemu' type='raw'/>
+           <source file='/path/to/old'/>
+           <target dev='vda' bus='virtio'/>
+         </disk>
+         <disk type='file' device='disk' snapshot='external'>
+           <driver name='qemu' type='raw'/>
+           <source file='/path/to/old2'/>
+           <target dev='vdb' bus='virtio'/>
+         </disk>
+         ...
+       </devices>
+     </domain>
+   </domainsnapshot>
+
+With that snapshot created, ``/path/to/old`` is the read-only backing file to
+the new active file ``/path/to/new``. The ``<domain>`` element within the
+snapshot xml records the state of the domain just before the snapshot; a call to
+``virDomainGetXMLDesc()`` will show that the domain has been changed to reflect
+the snapshot:
+
+::
+
+   <domain>
+     <name>fedora</name>
+     <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
+     <memory>1048576</memory>
+     ...
+     <devices>
+       <disk type='file' device='disk'>
+         <driver name='qemu' type='qcow2'/>
+         <source file='/path/to/new'/>
+         <target dev='vda' bus='virtio'/>
+       </disk>
+       <disk type='file' device='disk' snapshot='external'>
+         <driver name='qemu' type='raw'/>
+         <source file='/path/to/old2'/>
+         <target dev='vdb' bus='virtio'/>
+       </disk>
+       ...
+     </devices>
+   </domain>

docs/formatstorageencryption.html.in

@@ -143,7 +143,7 @@
     <h2><a id="example">Examples</a></h2>
 
     <p>
-      Assuming a <a href="formatsecret.html#VolumeUsageType">
+      Assuming a <a href="formatsecret.html#usage-type-volume">
       <code>luks volume type secret</code></a> is already defined,
       a simple example specifying use of the <code>luks</code> format
       for either volume creation without a specific cipher being defined or

docs/goals.html.in

@@ -1,67 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Terminology and goals</h1>
-    <p>To avoid ambiguity about the terms used, here are the definitions
-       for some of the specific concepts used in libvirt documentation:</p>
-    <ul>
-      <li>a <strong>node</strong> is a single physical machine</li>
-      <li>an <strong>hypervisor</strong> is a layer of software allowing to
-    virtualize a node in a set of virtual machines with possibly different
-    configurations than the node itself</li>
-      <li>a <strong>domain</strong> is an instance of an operating system
-    (or subsystem in the case of container virtualization) running on a
-    virtualized machine provided by the hypervisor</li>
-    </ul>
-    <p class="image">
-      <img alt="Hypervisor and domains running on a node" src="images/node.gif"/>
-    </p>
-    <p>Now we can define the goal of libvirt: <b> to provide a common and
-    stable layer sufficient to securely manage domains on a node, possibly
-    remote</b>.</p>
-    <p> As a result, libvirt should provide all APIs needed to do the
-    management, such as: provision, create, modify, monitor, control, migrate
-    and stop the domains - within the limits of the support of the hypervisor
-    for those operations.
-    Not all hypervisors provide the same operations; but if an operation is
-    useful for domain management of even one specific hypervisor it is worth
-    providing in libvirt.
-    Multiple nodes
-    may be accessed with libvirt simultaneously, but the APIs are limited to
-    single node operations. Node resource operations which are needed
-    for the management and provisioning of domains are also in the scope of
-    the libvirt API, such as interface setup, firewall rules, storage management
-    and general provisioning APIs. Libvirt will also provide the state
-    monitoring APIs needed to implement management policies, obviously
-    checking domain state but also exposing local node resource consumption.
-    </p>
-    <p>This implies the following sub-goals:</p>
-    <ul>
-      <li>All API can be carried remotely though secure APIs</li>
-      <li>While most API will be generic in term of hypervisor or Host OS,
-    some API may be targeted to a single virtualization environment
-    as long as the semantic for the operations from a domain management
-    perspective is clear</li>
-      <li>the API should allow to do efficiently and cleanly all the operations
-    needed to manage domains on a node, including resource provisioning and
-    setup</li>
-      <li>the API will not try to provide high level virtualization policies or
-    multi-nodes management features like load balancing, but the API should be
-    sufficient so they can be implemented on top of libvirt</li>
-      <li>stability of the API is a big concern, libvirt should isolate
-    applications from the frequent changes expected at the lower level of the
-    virtualization framework</li>
-      <li>the node being managed may be on a different physical machine than
-    the management program using libvirt, to this effect libvirt supports
-    remote access, but should only do so by using secure protocols.</li>
-      <li>libvirt will provide APIs to enumerate, monitor and use the resources
-    available on the managed node, including CPUs, memory, storage, networking,
-    and NUMA partitions.</li>
-    </ul>
-    <p>So libvirt is intended to be a building block for higher level
-    management tools and for applications focusing on virtualization of a
-    single node (the only exception being domain migration between node
-    capabilities which involves more than one node).</p>
-  </body>
-</html>

docs/goals.rst

@@ -0,0 +1,56 @@
+=====================
+Terminology and goals
+=====================
+
+To avoid ambiguity about the terms used, here are the definitions for some of
+the specific concepts used in libvirt documentation:
+
+-  a **node** is a single physical machine
+-  an **hypervisor** is a layer of software allowing to virtualize a node in a
+   set of virtual machines with possibly different configurations than the node
+   itself
+-  a **domain** is an instance of an operating system (or subsystem in the case
+   of container virtualization) running on a virtualized machine provided by the
+   hypervisor
+
+Now we can define the goal of libvirt: **to provide a common and stable layer
+sufficient to securely manage domains on a node, possibly remote**.
+
+As a result, libvirt should provide all APIs needed to do the management, such
+as: provision, create, modify, monitor, control, migrate and stop the domains -
+within the limits of the support of the hypervisor for those operations. Not all
+hypervisors provide the same operations; but if an operation is useful for
+domain management of even one specific hypervisor it is worth providing in
+libvirt. Multiple nodes may be accessed with libvirt simultaneously, but the
+APIs are limited to single node operations. Node resource operations which are
+needed for the management and provisioning of domains are also in the scope of
+the libvirt API, such as interface setup, firewall rules, storage management and
+general provisioning APIs. Libvirt will also provide the state monitoring APIs
+needed to implement management policies, obviously checking domain state but
+also exposing local node resource consumption.
+
+This implies the following sub-goals:
+
+-  All API can be carried remotely though secure APIs
+-  While most API will be generic in term of hypervisor or Host OS, some API may
+   be targeted to a single virtualization environment as long as the semantic
+   for the operations from a domain management perspective is clear
+-  the API should allow to do efficiently and cleanly all the operations needed
+   to manage domains on a node, including resource provisioning and setup
+-  the API will not try to provide high level virtualization policies or
+   multi-nodes management features like load balancing, but the API should be
+   sufficient so they can be implemented on top of libvirt
+-  stability of the API is a big concern, libvirt should isolate applications
+   from the frequent changes expected at the lower level of the virtualization
+   framework
+-  the node being managed may be on a different physical machine than the
+   management program using libvirt, to this effect libvirt supports remote
+   access, but should only do so by using secure protocols.
+-  libvirt will provide APIs to enumerate, monitor and use the resources
+   available on the managed node, including CPUs, memory, storage, networking,
+   and NUMA partitions.
+
+So libvirt is intended to be a building block for higher level management tools
+and for applications focusing on virtualization of a single node (the only
+exception being domain migration between node capabilities which involves more
+than one node).

docs/governance.html.in

@@ -1,298 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Project governance</h1>
-
-    <ul id="toc"></ul>
-
-    <p>
-      The libvirt project operates as a meritocratic, consensus-based community.
-      Anyone with an interest in the project can join the community, contributing
-      to the ongoing development of the project's work. This pages describes how
-      that participation takes place and how contributors earn merit, and thus
-      influence, within the community.
-    </p>
-
-    <h2><a id="codeofconduct">Code of conduct</a></h2>
-
-    <p>
-      The libvirt project community covers people from a wide variety of
-      countries, backgrounds and positions. This global diversity is a great
-      strength of the project, but can also lead to communication issues,
-      which may in turn cause unhappiness. To maximise happiness of the
-      project community taken as a whole, all members (whether users,
-      contributors or committers) are expected to abide by the project's
-      code of conduct. At a high level the code can be summarized as
-      <em>"be excellent to each other"</em>. Expanding on this:
-    </p>
-
-    <ul>
-      <li><strong>Be respectful:</strong> disagreements between people are to
-        be expected and are usually the sign of healthy debate and engagement.
-        Disagreements can lead to frustration and even anger for some members.
-        Turning to personal insults, intimidation or threatening behaviour does
-        not improve the situation though. Participants should thus take care to
-        ensure all communications / interactions stay professional at all times.</li>
-
-      <li><strong>Be considerate:</strong> remember that the community has members
-        with a diverse background many of whom have English as a second language.
-        What might appear impolite, may simply be a result of a lack of knowledge
-        of the English language. Bear in mind that actions will have an impact
-        on other community members and the project as a whole, so take potential
-        consequences into account before pursuing a course of action.</li>
-
-      <li><strong>Be forgiving:</strong> humans are fallible and as such prone
-        to make mistakes and inexplicably change their positions at times. Don't
-        assume that other members are acting with malicious intent. Be prepared
-        to forgive people who make mistakes and assist each other in learning
-        from them. Playing a blame game doesn't help anyone.</li>
-    </ul>
-
-    <h2><a id="roles">Roles and responsibilities</a></h2>
-
-    <h3><a href="users">Users</a></h3>
-
-    <p>
-      The users are anyone who has a need for the output of the project.
-      There are no rules or requirements to become a user of libvirt. Even
-      if the software does not yet work on their OS platform, a person can
-      be considered a potential future user and welcomed to participate.
-    </p>
-
-    <p>
-      Participation by users is key to ensuring the project moves in the
-      right direction, satisfying their real world needs. Users are
-      encouraged to participate in the broader libvirt community in any
-      number of ways:
-    </p>
-
-    <ul>
-      <li>Evangelism: spread the word about what libvirt is doing, how it
-        helps solve your problems. This can be via blog articles, social
-        media postings, video blogs, user group / conference presentations
-        and any other method of disseminating information</li>
-      <li>Feedback: let the developers know about what does and does not
-        work with the project. Talk to developers on the project's
-        IRC channel and mailing list, or find them at conferences. Tell
-        them what gaps the project has or where they should look for
-        future development</li>
-      <li>Moral support: developers live for recognition of the positive
-        impact their work has on users' lives. Give thanks to the developers
-        when evangelising the project, or when meeting them at user groups,
-        conferences, etc.</li>
-    </ul>
-
-    <p>
-      The above is not an exhaustive list of things users can do to
-      participate in the project. Further ideas and suggestions are
-      welcome. Users are encouraged to take their participation
-      further and become contributors to the project in any of the
-      ways listed in the next section.
-    </p>
-
-    <h3><a id="contributors">Contributors</a></h3>
-
-    <p>
-      The contributors are community members who have some concrete impact
-      to the ongoing development of the project. There are many ways in which
-      members can contribute, with no requirement to be a software engineer.
-      Many users can in fact consider themselves contributors merely by
-      engaging in evangelism for the project.
-    </p>
-
-    <ul>
-      <li>Bug reporting: improve the quality of the project by reporting
-        any problems found either to the project's own bug tracker, or to
-        that of the OS vendor shipping the libvirt code.</li>
-      <li>User help: join the <a href="contact.html">IRC channel or mailing list</a>
-        to assist or advice other users in troubleshooting the problems they face.</li>
-      <li>Feature requests: help set the direction for future work by
-        reporting details of features which are missing to the project's
-        own bug tracker or mailing lists.</li>
-      <li>Graphical design: contribute to the development of the project's
-        websites / wiki brand with improved graphics, styling or layout.</li>
-      <li>Code development: write and submit patches to address bugs or implement
-        new features</li>
-      <li>Architectural design: improve the usefulness of the project
-        by providing feedback on the design of proposed features, to
-        ensure they satisfy the broadest applicable needs and survive
-        the long term</li>
-      <li>Code review: look at patches which are submitted and critique
-        the code to identify bugs, potential design problems or other
-        issues which should be addressed before the code is accepted</li>
-      <li>Documentation: contribute to content on personal blogs, the
-        website, wiki, code comments, or any of the formal documentation
-        efforts.</li>
-      <li>Translation: join the Fedora transifex community to improve the
-        quality of translations needed by the libvirt project.</li>
-      <li>Testing: try proposed patches or release candidates and report
-        whether the build passes and the changes work as expected.</li>
-    </ul>
-
-    <p>
-      The above is not an exhaustive list of things members can do to
-      contribute to the project. Further ideas and suggestions are
-      welcome.
-    </p>
-
-    <p>
-      There are no special requirements to becoming a contributor other
-      than having the interest and ability to provide a contribution. The
-      libvirt project <strong>does not require</strong> any
-      <em>"Contributor License Agreement"</em>
-      to be signed prior to engagement with the community. However for
-      contributing patches, providing a 'Signed-off-by' line with the
-      author's legal name and e-mail address to demonstrate agreement
-      and compliance with the <a href="https://developercertificate.org/">
-      Developer Certificate of Origin</a> is required.
-    </p>
-
-    <p>
-      In making a non-patch contribution to the project, the community
-      member is implicitly stating that they accept the terms of the license
-      under which the work they are contributing to is distributed. They are
-      also implicitly stating that they have the legal right to make the
-      contribution, if doing so on behalf of a broader organization /
-      company. Most of the project's code is distributed under the GNU
-      Lesser General Public License, version 2.1 or later. Details of the
-      exact license under which contributions will be presumed to be
-      covered are found in the source repositories, or website in question.
-    </p>
-
-    <h3><a id="committers">Committers</a></h3>
-
-    <p>
-      The committers are the subset of contributors who have direct access
-      to commit code to the project's primary source code repositories, which
-      are currently using the GIT software. The committers are chosen based
-      on the quality of their contributions over a period of time. This includes
-      both the quality of code they submit, as well as the quality of reviews
-      they provide on other contributors' submissions and a demonstration that
-      they understand day-to-day operation of the project and its goals. There
-      is no minimum level of contribution required in order to become a committer,
-      though 2-3 months worth of quality contribution would be a rough guide.
-    </p>
-
-    <p>
-      There are no special requirements to becoming a committer other than to
-      have shown a willingness and ability to contribute to the project over
-      an extended period of time. Proposals for elevating contributors to
-      committers are typically made by existing committers, though contributors
-      are also welcome to make proposals. The decision to approve the elevation
-      of a contributor to a committer is made through "rough consensus" between
-      the existing committers.
-    </p>
-
-    <p>
-      The aim in elevating contributors to committers is to ensure that there
-      is a broad base of experience and expertize across all areas of the
-      project's work. Committers are not required to have knowledge across
-      all areas of the project's work. While an approved committer has the
-      technical ability to commit code to any area of the project, by convention
-      they will only commit to areas they feel themselves to be qualified to
-      evaluate the contribution. If in doubt, committers will defer to the
-      opinion of other committers with greater expertize in an area.
-    </p>
-
-    <p>
-      The committers hold the ultimate control over what contributions are
-      accepted by the project, however, this does not mean they have the
-      right to do whatever they want. Where there is debate and disagreement
-      between contributors, committers are expected to look at the issues with
-      an unbiased point of view and help achieve a "rough consensus". If the
-      committer has a conflict of interest in the discussion, for example due
-      to their position of employment, they are expected to put the needs of
-      the community project first. If they cannot put the community project
-      first, they must declare their conflict of interest, and allow other
-      non-conflicted committers to make any final decision.
-    </p>
-
-    <p>
-      The committers are expected to monitor contributions to areas of the
-      project where they have expertize and ensure that either some form of
-      feedback is provided to the contributor, or to accept their contribution.
-      There is no formal minimum level of approval required to accept a
-      contribution. Positive review by any committer experienced in the area
-      of work is considered to be enough to justify acceptance in normal
-      circumstances. Where one committer explicitly rejects a contribution,
-      however, other committers should not override that rejection without
-      first establishing a "rough consensus" amongst the broader group of
-      committers.
-    </p>
-
-    <p>
-      Being a committer is a privilege, not a right. In exceptional
-      circumstances, the privilege may be removed from an active
-      contributor. Such decisions will be taken based on "rough
-      consensus" amongst other committers. In the event that a committer
-      is no longer able to participate in the project, after some period
-      of inactivity passes, they may be asked to confirm that they wish
-      to retain their role as a committer.
-    </p>
-
-    <h3><a id="secteam">Security team</a></h3>
-
-    <p>
-      The security team consists of a subset of the project committers
-      along with representatives from vendors shipping the project's
-      software. The subset of project committers is chosen to be the
-      minimal size necessary to provide expertise spanning most of
-      the project's work. Further project committers may be requested
-      to engage in resolving specific security issues on a case by
-      case basis. Any vendor who is shipping the project's software
-      may submit a request for one or more of their representatives
-      to join the security team. Such requests must by approved by
-      existing members of the team vouching for the integrity of
-      the nominated person or organization.
-    </p>
-
-    <p>
-      Members of the security team are responsible for triaging and
-      resolving any security issues that are reported to the project.
-      They are expected to abide by the project's documented
-      <a href="securityprocess.html">security process</a>. In particular
-      they must respect any embargo period agreed amongst the team
-      before disclosing a private issue.
-    </p>
-
-    <h2><a id="roughconsensus">Rough consensus</a></h2>
-
-    <p>
-      A core concept for governance of the project described above is
-      that of "rough consensus". To expand on this, it is a process
-      of decision making that involves the following steps
-    </p>
-
-    <ul>
-      <li>Proposal</li>
-      <li>Discussion</li>
-      <li>Vote (exceptional circumstances only)</li>
-      <li>Decision</li>
-    </ul>
-
-    <p>
-      To put this into words, any contributor is welcome to make a proposal
-      for consideration. Any contributor may participate in the discussions
-      around the proposal. The discussion will usually result in agreement
-      between the interested parties, or at least agreement between the
-      committers. Only in the very exceptional circumstance where there
-      is disagreement between committers, would a vote be considered.
-      Even in these exceptional circumstances, it is usually found to be
-      obvious what the majority opinion of the committers is. In the event
-      that even a formal vote is tied, the committers will have to hold
-      ongoing discussions until the stalemate is resolved or the proposal
-      withdrawn.
-    </p>
-
-    <p>
-      The overall goal of the "rough consensus" process is to ensure that
-      decisions can be made within the project, with a minimum level of
-      bureaucracy and process. Implicit in this is that any person who does
-      not explicitly reject to a proposal is assumed to be supportive, or
-      at least agnostic.
-    </p>
-
-
-  </body>
-</html>

docs/governance.rst

@@ -0,0 +1,232 @@
+.. role:: anchor(raw)
+   :format: html
+
+==================
+Project governance
+==================
+
+.. contents::
+
+The libvirt project operates as a meritocratic, consensus-based community.
+Anyone with an interest in the project can join the community, contributing to
+the ongoing development of the project's work. This pages describes how that
+participation takes place and how contributors earn merit, and thus influence,
+within the community.
+
+:anchor:`<a id="codeofconduct"/>`
+
+Code of conduct
+---------------
+
+The libvirt project community covers people from a wide variety of countries,
+backgrounds and positions. This global diversity is a great strength of the
+project, but can also lead to communication issues, which may in turn cause
+unhappiness. To maximise happiness of the project community taken as a whole,
+all members (whether users, contributors or committers) are expected to abide by
+the project's code of conduct. At a high level the code can be summarized as
+*"be excellent to each other"*. Expanding on this:
+
+-  **Be respectful:** disagreements between people are to be expected and are
+   usually the sign of healthy debate and engagement. Disagreements can lead to
+   frustration and even anger for some members. Turning to personal insults,
+   intimidation or threatening behaviour does not improve the situation though.
+   Participants should thus take care to ensure all communications /
+   interactions stay professional at all times.
+-  **Be considerate:** remember that the community has members with a diverse
+   background many of whom have English as a second language. What might appear
+   impolite, may simply be a result of a lack of knowledge of the English
+   language. Bear in mind that actions will have an impact on other community
+   members and the project as a whole, so take potential consequences into
+   account before pursuing a course of action.
+-  **Be forgiving:** humans are fallible and as such prone to make mistakes and
+   inexplicably change their positions at times. Don't assume that other members
+   are acting with malicious intent. Be prepared to forgive people who make
+   mistakes and assist each other in learning from them. Playing a blame game
+   doesn't help anyone.
+
+Roles and responsibilities
+--------------------------
+
+Users
+~~~~~
+
+The users are anyone who has a need for the output of the project. There are no
+rules or requirements to become a user of libvirt. Even if the software does not
+yet work on their OS platform, a person can be considered a potential future
+user and welcomed to participate.
+
+Participation by users is key to ensuring the project moves in the right
+direction, satisfying their real world needs. Users are encouraged to
+participate in the broader libvirt community in any number of ways:
+
+-  Evangelism: spread the word about what libvirt is doing, how it helps solve
+   your problems. This can be via blog articles, social media postings, video
+   blogs, user group / conference presentations and any other method of
+   disseminating information
+-  Feedback: let the developers know about what does and does not work with the
+   project. Talk to developers on the project's IRC channel and mailing list, or
+   find them at conferences. Tell them what gaps the project has or where they
+   should look for future development
+-  Moral support: developers live for recognition of the positive impact their
+   work has on users' lives. Give thanks to the developers when evangelising the
+   project, or when meeting them at user groups, conferences, etc.
+
+The above is not an exhaustive list of things users can do to participate in the
+project. Further ideas and suggestions are welcome. Users are encouraged to take
+their participation further and become contributors to the project in any of the
+ways listed in the next section.
+
+Contributors
+~~~~~~~~~~~~
+
+The contributors are community members who have some concrete impact to the
+ongoing development of the project. There are many ways in which members can
+contribute, with no requirement to be a software engineer. Many users can in
+fact consider themselves contributors merely by engaging in evangelism for the
+project.
+
+-  Bug reporting: improve the quality of the project by reporting any problems
+   found either to the project's own bug tracker, or to that of the OS vendor
+   shipping the libvirt code.
+-  User help: join the `IRC channel or mailing list <contact.html>`__ to assist
+   or advice other users in troubleshooting the problems they face.
+-  Feature requests: help set the direction for future work by reporting details
+   of features which are missing to the project's own bug tracker or mailing
+   lists.
+-  Graphical design: contribute to the development of the project's websites /
+   wiki brand with improved graphics, styling or layout.
+-  Code development: write and submit patches to address bugs or implement new
+   features
+-  Architectural design: improve the usefulness of the project by providing
+   feedback on the design of proposed features, to ensure they satisfy the
+   broadest applicable needs and survive the long term
+-  Code review: look at patches which are submitted and critique the code to
+   identify bugs, potential design problems or other issues which should be
+   addressed before the code is accepted
+-  Documentation: contribute to content on personal blogs, the website, wiki,
+   code comments, or any of the formal documentation efforts.
+-  Translation: join the Fedora transifex community to improve the quality of
+   translations needed by the libvirt project.
+-  Testing: try proposed patches or release candidates and report whether the
+   build passes and the changes work as expected.
+
+The above is not an exhaustive list of things members can do to contribute to
+the project. Further ideas and suggestions are welcome.
+
+There are no special requirements to becoming a contributor other than having
+the interest and ability to provide a contribution. The libvirt project **does
+not require** any *"Contributor License Agreement"* to be signed prior to
+engagement with the community. However for contributing patches, providing a
+'Signed-off-by' line with the author's legal name and e-mail address to
+demonstrate agreement and compliance with the `Developer Certificate of
+Origin <https://developercertificate.org/>`__ is required.
+
+In making a non-patch contribution to the project, the community member is
+implicitly stating that they accept the terms of the license under which the
+work they are contributing to is distributed. They are also implicitly stating
+that they have the legal right to make the contribution, if doing so on behalf
+of a broader organization / company. Most of the project's code is distributed
+under the GNU Lesser General Public License, version 2.1 or later. Details of
+the exact license under which contributions will be presumed to be covered are
+found in the source repositories, or website in question.
+
+Committers
+~~~~~~~~~~
+
+The committers are the subset of contributors who have direct access to commit
+code to the project's primary source code repositories, which are currently
+using the GIT software. The committers are chosen based on the quality of their
+contributions over a period of time. This includes both the quality of code they
+submit, as well as the quality of reviews they provide on other contributors'
+submissions and a demonstration that they understand day-to-day operation of the
+project and its goals. There is no minimum level of contribution required in
+order to become a committer, though 2-3 months worth of quality contribution
+would be a rough guide.
+
+There are no special requirements to becoming a committer other than to have
+shown a willingness and ability to contribute to the project over an extended
+period of time. Proposals for elevating contributors to committers are typically
+made by existing committers, though contributors are also welcome to make
+proposals. The decision to approve the elevation of a contributor to a committer
+is made through "rough consensus" between the existing committers.
+
+The aim in elevating contributors to committers is to ensure that there is a
+broad base of experience and expertize across all areas of the project's work.
+Committers are not required to have knowledge across all areas of the project's
+work. While an approved committer has the technical ability to commit code to
+any area of the project, by convention they will only commit to areas they feel
+themselves to be qualified to evaluate the contribution. If in doubt, committers
+will defer to the opinion of other committers with greater expertize in an area.
+
+The committers hold the ultimate control over what contributions are accepted by
+the project, however, this does not mean they have the right to do whatever they
+want. Where there is debate and disagreement between contributors, committers
+are expected to look at the issues with an unbiased point of view and help
+achieve a "rough consensus". If the committer has a conflict of interest in the
+discussion, for example due to their position of employment, they are expected
+to put the needs of the community project first. If they cannot put the
+community project first, they must declare their conflict of interest, and allow
+other non-conflicted committers to make any final decision.
+
+The committers are expected to monitor contributions to areas of the project
+where they have expertize and ensure that either some form of feedback is
+provided to the contributor, or to accept their contribution. There is no formal
+minimum level of approval required to accept a contribution. Positive review by
+any committer experienced in the area of work is considered to be enough to
+justify acceptance in normal circumstances. Where one committer explicitly
+rejects a contribution, however, other committers should not override that
+rejection without first establishing a "rough consensus" amongst the broader
+group of committers.
+
+Being a committer is a privilege, not a right. In exceptional circumstances, the
+privilege may be removed from an active contributor. Such decisions will be
+taken based on "rough consensus" amongst other committers. In the event that a
+committer is no longer able to participate in the project, after some period of
+inactivity passes, they may be asked to confirm that they wish to retain their
+role as a committer.
+
+Security team
+~~~~~~~~~~~~~
+
+The security team consists of a subset of the project committers along with
+representatives from vendors shipping the project's software. The subset of
+project committers is chosen to be the minimal size necessary to provide
+expertise spanning most of the project's work. Further project committers may be
+requested to engage in resolving specific security issues on a case by case
+basis. Any vendor who is shipping the project's software may submit a request
+for one or more of their representatives to join the security team. Such
+requests must by approved by existing members of the team vouching for the
+integrity of the nominated person or organization.
+
+Members of the security team are responsible for triaging and resolving any
+security issues that are reported to the project. They are expected to abide by
+the project's documented `security process <securityprocess.html>`__. In
+particular they must respect any embargo period agreed amongst the team before
+disclosing a private issue.
+
+Rough consensus
+---------------
+
+A core concept for governance of the project described above is that of "rough
+consensus". To expand on this, it is a process of decision making that involves
+the following steps
+
+-  Proposal
+-  Discussion
+-  Vote (exceptional circumstances only)
+-  Decision
+
+To put this into words, any contributor is welcome to make a proposal for
+consideration. Any contributor may participate in the discussions around the
+proposal. The discussion will usually result in agreement between the interested
+parties, or at least agreement between the committers. Only in the very
+exceptional circumstance where there is disagreement between committers, would a
+vote be considered. Even in these exceptional circumstances, it is usually found
+to be obvious what the majority opinion of the committers is. In the event that
+even a formal vote is tied, the committers will have to hold ongoing discussions
+until the stalemate is resolved or the proposal withdrawn.
+
+The overall goal of the "rough consensus" process is to ensure that decisions
+can be made within the project, with a minimum level of bureaucracy and process.
+Implicit in this is that any person who does not explicitly reject to a proposal
+is assumed to be supportive, or at least agnostic.

docs/hacking.rst

@@ -72,7 +72,6 @@ This page only covers the very basics, so it's recommended that
 you also take a look at the following documents:
 
 -  `Programming languages <programming-languages.html>`__
--  `Developer tooling <developer-tooling.html>`__
 -  `Advanced test suite usage <advanced-tests.html>`__
 -  `Adoption of GLib APIs <glib-adoption.html>`__
 -  `Committer guidelines <committer-guidelines.html>`__

docs/images/meson.build

@@ -10,7 +10,6 @@ docs_image_files = [
   'migration-native.png',
   'migration-tunnel.png',
   'migration-unmanaged-direct.png',
-  'node.gif',
 ]
 
 install_data(docs_image_files, install_dir: docs_html_dir / 'images')

docs/images/node.svg

@@ -1,36 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!-- Creator: fig2dev Version 3.2.7b-dev -->
-<!-- CreationDate: 2020-07-10 10:25:51 -->
-<!-- Magnification: 1 -->
-<svg	xmlns="http://www.w3.org/2000/svg"
-	xmlns:xlink="http://www.w3.org/1999/xlink"
-	width="150pt" height="159pt"
-	viewBox="963 1488 2490 2649">
-<g fill="none">
-<!-- Line -->
-<rect x="1275" y="1800" width="1275" height="450" rx="105"
-	stroke="#000000" stroke-width="8px"/>
-<!-- Text -->
-<text xml:space="preserve" x="1500" y="2100" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="240" text-anchor="start">Domain</text>
-<!-- Line -->
-<rect x="1275" y="2325" width="1275" height="450" rx="105"
-	stroke="#000000" stroke-width="8px"/>
-<!-- Text -->
-<text xml:space="preserve" x="1500" y="2625" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="240" text-anchor="start">Domain</text>
-<!-- Line -->
-<rect x="1275" y="2850" width="1275" height="450" rx="105"
-	stroke="#000000" stroke-width="8px"/>
-<!-- Text -->
-<text xml:space="preserve" x="1500" y="3150" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="240" text-anchor="start">Domain</text>
-<!-- Line -->
-<rect x="975" y="1500" width="2400" height="2625"
-	stroke="#000000" stroke-width="8px"/>
-<!-- Line -->
-<rect x="1125" y="3450" width="2100" height="525" rx="105"
-	stroke="#000000" stroke-width="8px"/>
-<!-- Text -->
-<text xml:space="preserve" x="1500" y="3825" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="240" text-anchor="start">Hypervisor</text>
-<!-- Text -->
-<text xml:space="preserve" x="2700" y="2850" fill="#000000" font-family="Times" font-style="normal" font-weight="normal" font-size="240" text-anchor="start">Node</text>
-</g>
-</svg>

docs/index.html.in

@@ -21,13 +21,15 @@
         <li>is accessible from C, Python, Perl, Go and more</li>
         <li>is licensed under open source licenses</li>
         <li>supports <a href="drvqemu.html">KVM</a>,
+          <a href="drvqemu.html">Hypervisor.framework</a>,
           <a href="drvqemu.html">QEMU</a>, <a href="drvxen.html">Xen</a>,
           <a href="drvvirtuozzo.html">Virtuozzo</a>,
           <a href="drvesx.html">VMWare ESX</a>,
           <a href="drvlxc.html">LXC</a>,
           <a href="drvbhyve.html">BHyve</a> and
           <a href="drivers.html">more</a></li>
-        <li>targets Linux, FreeBSD, <a href="windows.html">Windows</a> and macOS</li>
+        <li>targets Linux, FreeBSD, <a href="windows.html">Windows</a> and
+          <a href="macos.html">macOS</a></li>
         <li>is used by many <a href="apps.html">applications</a></li>
       </ul>
       <p>Recent / forthcoming <a href="news.html">release changes</a></p>

docs/kbase/debuglogs.rst

@@ -5,7 +5,7 @@ Debug Logs
 .. contents::
 
 Turning on debug logs
----------------------
+=====================
 
 If you `report a bug <https://gitlab.com/libvirt/libvirt/-/issues/new>`__
 against libvirt, in most cases you will be asked to attach debug logs. These
@@ -17,69 +17,184 @@ Moreover, libvirt catches stderr of all running domains. These can be useful as
 well.
 
 
-How to turn on debug logs for libvirt
+Logging settings in libvirt
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===========================
+
+Log levels
+----------
+
+Libvirt log messages are classified into 4 priority levels; the higher the
+priority level, the less is the volume of produced messages.
+
+The log level setting is controlled by the ``log_filters`` and ``log_outputs``
+settings explained in the `Log outputs`_ and `Log filters`_ sections
+respectively.
+
+  * ``1: DEBUG``
+  * ``2: INFO``
+  * ``3: WARNING``
+  * ``4: ERROR``
+
+For debugging it's necessary to capture the ``DEBUG`` level entries as the name
+implies.
+
+Log outputs
+-----------
+
+Log outputs describe where the log messages are being recorded. The outputs
+are described by a space-separated list of tuples in the following format:
+
+::
+
+  level:output
+
+``level`` refers to the minimum priority level of entries recorded in the output.
+
+``output`` is one of the following:
+
+  ``file:FILENAME``
+    Logging messages are appended to FILENAME.
+
+  ``journald``
+    Logging goes to the ``journald`` logging daemon.
+
+  ``stderr``
+    Logging goes to the standard error output stream of the libvirt daemon.
+
+  ``syslog:name``
+    Logging goes to syslogd. ``name`` is used to identify the entries.
+
+The default output on systems running ``journald`` is ``3:journald``. Note that
+``journald`` can throttle the amount of logs per process so in order to capture
+debug logs of a libvirt daemon should go to a file instead (in addition to
+theoriginal logging daemon), e.g.:
+
+::
+
+  "1:file:/var/log/libvirt/libvirtd.log 3:journald"
+
+
+Log filters
+-----------
+
+Log filters, as the name suggest, help filtering out messages which are
+irrelevant to the cause.  The log filters is a space-separated list of tuples
+list of tuples using the ``level:identifier`` format. Each filter defined this
+way will then limit messages coming from a module matching the ``identifier``
+pattern (accepts globs too) to the given ``level``."
+
+As ``identifier`` is based on internal naming of modules, preferred way of
+configuring your filters is to start with the `Example filter settings`_.
+
+The rule of thumb here is to have more logs rather than less and miss something
+important.
+
+Libvirt daemons logging configuration
+=====================================
+
+Libvirt daemons can be configured either via a config file or via the
+administration API. The configuration location depends on multiple factors.
+
+Session vs system daemons
+-------------------------
+
+Libvirt daemons run either in the ``system`` mode or on ``session`` (user)
+mode, depending on the configuration of the host and available permission
+levels.
+
+The `connection URI <https://libvirt.org/uri.html>`__ influences which daemon
+the client will communicate with.
+
+System daemon mode
+~~~~~~~~~~~~~~~~~~
+  * all connection URIs end in ``/system`` e.g. ``qemu:///system``
+
+  * config files are usually placed in ``/etc/libvirt``
+
+Session daemon mode
+~~~~~~~~~~~~~~~~~~~
+
+  * connection URIs end in ``/session``
+
+  * config files are usually placed in ``$XDG_CONFIG_HOME/libvirt/`` directory
+
+Modular vs. monolithic daemons
+------------------------------
+
+While there is only a single 'libvirtd.conf' configuration file in case of the
+monolithic daemon setup, each of the modular daemons has their own
+configuration file giving you a lot of possibilities how to configure them
+individually including logging. Realistically though, logging will have to be
+configured only for a single or a couple of daemons in case debug logs are
+requested.
+
+
+Refer to `documentation about daemons <../daemons.html#checking-whether-modular-monolithic-mode-is-in-use>`__
+to figure out which is in use by your system.
+
+Modular daemons
+~~~~~~~~~~~~~~~
+
+The configuration of modular daemons is in file named after the daemon. E.g.
+for ``qemu:///system`` connection this is the ``virtqemud`` daemon and
+correspondingly:
+
+  * ``virtqemud.conf`` config file is used
+
+  * ``virtqemud:///system`` or ``virtqemud:///session`` admin URI is used
+
+Monolithic daemon
+~~~~~~~~~~~~~~~~~
+
+   * ``libvirtd.conf`` config file is used
+
+   * ``libvirtd:///system`` or ``libvirtd:///session`` admin URI is used
+     when the modular qemu hypervisor driver ``virtqemud``
 
 Persistent setting
-^^^^^^^^^^^^^^^^^^
+------------------
 
-The daemon configuration files location is dependent on `connection
+In order to setup libvirt logging persistently, follow the steps below:
-URI <https://libvirt.org/uri.html>`__. For ``qemu:///system``:
 
+-  open the appropriate daemon config file in your favourite editor ::
 
+     /etc/libvirt/virtqemud.conf
+     /etc/libvirt/libvirtd.conf
+     $XDG_CONFIG_HOME/libvirt/libvirtd.conf
+     $XDG_CONFIG_HOME/libvirt/virtqemud.conf
 
--  open ``/etc/libvirt/libvirtd.conf`` in your favourite editor
+-  find & replace, or set the appropriate `Log outputs`_ and `Log filters`_, e.g ::
--  find & replace, or set these variables:
 
-::
+     log_filters="3:remote 4:event 3:util.json 3:rpc 1:*"
-
+     log_outputs="1:file:/var/log/libvirt/libvirtd.log"
-   # LEGACY SETTINGS PRIOR LIBVIRT 4.4.0 SEE BELOW! #
-   log_level = 1
-   log_filters="1:qemu 3:remote 4:event 3:util.json 3:rpc"
-   log_outputs="1:file:/var/log/libvirt/libvirtd.log"
-
-::
-
-   # PREFERRED SETTINGS AFTER LIBVIRT 4.4.0 #
-   log_filters="3:remote 4:event 3:util.json 3:rpc 1:*"
-   log_outputs="1:file:/var/log/libvirt/libvirtd.log"
 
 -  save and exit
--  restart libvirtd service
+-  restart the corresponding service/daemon e.g. ::
 
-::
+    systemctl restart virtqemud.socket
-
+    systemctl restart libvirtd.socket
-   systemctl restart libvirtd.service
+    systemctl restart libvirtd.service
-
-In the config variables above, we have set logging level to 1 (debug level), set
-some filters (to filter out noise), e.g. from rpc only warnings (=level 3) and
-above will be reported. The logs are saved into
-``/var/log/libvirt/libvirtd.log``. Since libvirt **4.4.0** log filters support
-shell globbing, therefore the usage of ``log_level`` is considered deprecated in
-favour of pure usage of ``log_filters``.
-
-In case you want to get the client logs, you need to set this environment
-variable:
-
-::
-
-   export LIBVIRT_LOG_OUTPUTS="1:file:/tmp/libvirt_client.log"
 
 
-However, when you are using the session mode ``qemu:///session`` or you run the
+*Note:* Libvirt prior to the ``libvirt-4.4.0`` release didn't support globbing
-``libvirtd`` as unprivileged user you will find configuration file under
+patterns and thus requires more configuration. See
-``$XDG_CONFIG_HOME/libvirt/libvirtd.conf``.
+`Legacy (pre-4.4.0) libvirt daemon logging configuration`_.
 
 Runtime setting
-^^^^^^^^^^^^^^^
+---------------
 
 Debugging anomalies can be very painful, especially when trying to reproduce it
 after the daemon restarts, since the new session can make the anomaly
 "disappear". Therefore, it's possible to enable the debug logs during runtime
-using libvirt administration API. To use it conveniently, there's a virt-admin
+using libvirt administration API. To use it conveniently, there's the
-client provided by the libvirt-admin package. Use the package manager provided
+``virt-admin`` client provided by the ``libvirt-admin`` package. Use the
-by your distribution to install this package. Once you have it installed, run
+package manager provided by your distribution to install this package.
-the following as root to see the set of log filters currently being active:
+
+**Important**: Substitute ``virt-admin -c $ADMIN_URI`` according to the
+guideline in the sections above in place of ``virt-admin`` in the examples
+below if needed.
+
+The following command allows to query the list of currently active log filters:
 
 ::
 
@@ -91,12 +206,6 @@ own set of filters:
 
 ::
 
-   ## LEGACY APPROACH ENUMERATING ALL THE DESIRED MODULES ##
-   # virt-admin daemon-log-filters "1:util 1:libvirt 1:storage 1:network 1:nodedev 1:qemu"
-
-::
-
-   ## CURRENT APPROACH USING SHELL GLOBBING ##
    # virt-admin daemon-log-filters "3:remote 4:util.json 4:rpc 1:*"
 
 Analogically, the same procedure can be performed with log outputs:
@@ -112,7 +221,7 @@ once you're finished debugging, just remember to save the original sets of
 filters and outputs and restore them at the end the same way as described above.
 
 Removing filters and outputs
-''''''''''''''''''''''''''''
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It's also possible to remove all the filters and produce an enormous log file,
 but it is not recommended since some of libvirt's modules can produce a large
@@ -135,8 +244,45 @@ setting which depends on the host configuration, *journald* in our case:
    # virt-admin daemon-log-outputs ""
     Logging outputs: 2:journald
 
+Legacy (pre-4.4.0) libvirt daemon logging configuration
+-------------------------------------------------------
+
+Old libvirt versions didn't support globbing (e.g. ``1:*``) to configure
+logging, thus it's required to explicitly set logging level to 1 (debug level)
+with the ``log_level`` setting and then filter out the noise with a tailored log
+``log_filters`` string.
+
+::
+
+   # LEGACY SETTINGS PRIOR LIBVIRT 4.4.0
+   log_level = 1
+   log_filters="1:qemu 3:remote 4:event 3:util.json 3:rpc"
+   log_outputs="1:file:/var/log/libvirt/libvirtd.log"
+
+
+Or using ``virt-admin``:
+
+::
+
+   ## LEGACY APPROACH ENUMERATING ALL THE DESIRED MODULES ##
+   # virt-admin daemon-log-filters "1:util 1:libvirt 1:storage 1:network 1:nodedev 1:qemu"
+
+Client library logging
+======================
+
+By default the client library doesn't produce any logs and usually usually it's
+not very interesting on its own anyway.
+
+In case you want to get the client logs, logging is controlled via the
+``LIBVIRT_LOG_OUTPUTS`` and ``LIBVIRT_LOG_FILTERS`` environment variables.
+Generally when client logs are needed make sure you don't filter them:
+
+::
+
+   export LIBVIRT_LOG_OUTPUTS="1:file:/tmp/libvirt_client.log"
+
 What to attach?
----------------
+===============
 
 Now you should go and reproduce the bug. Once you're finished, attach:
 
@@ -154,9 +300,11 @@ Now you should go and reproduce the bug. Once you're finished, attach:
 -  If you are asked for client logs, ``/tmp/libvirt_client.log``.
 -  Ideally don't tear down the environment in case additional information is
    required.
+-  Consider whether you view any of the information in the debug logs
+   sensitive: `Sensitive information in debug logs`_.
 
 Example filter settings
------------------------
+=======================
 
 Some filter setting suggestions for debugging more specific things. Unless it's
 explicitly stated, these work on libvirt 4.4.0 and later. Please note that some
@@ -164,7 +312,7 @@ of the filters below may not log enough information for filing a proper libvirt
 bug. Usually it's better to log more than less.
 
 Targeted logging for debugging QEMU VMs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------
 
 Specifying only some sections allows for a targeted filter configuration which
 works on all versions and is sufficient for most cases.
@@ -174,7 +322,7 @@ works on all versions and is sufficient for most cases.
     1:libvirt 1:qemu 1:conf 1:security 3:event 3:json 3:file 3:object 1:util
 
 Less verbose logging for QEMU VMs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 Some subsystems are very noisy and usually not the culprit of the problems. They
 can be silenced individually for a less verbose log while still logging
@@ -186,10 +334,32 @@ A permissive filter is good for development use cases.
     3:remote 4:event 3:util.json 3:util.object 3:util.dbus 3:util.netlink 3:node_device 3:rpc 3:access 1:*
 
 Minimalistic QEMU QMP monitor logging
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 This filter logs only QMP traffic and skips most of libvirt's messages.
 
 ::
 
     2:qemu.qemu_monitor 3:*
+
+Sensitive information in debug logs
+===================================
+
+Debug logs may contain information that certain users may consider sensitive
+although generally it's okay to share debuglogs publicly.
+
+Information which could be deemed sensitive:
+
+ - hostname of the host
+ - names of VMs and other objects
+ - paths to disk images
+ - IP addresses of guests and the host
+ - hostnames/IP addresses of disks accessed via network
+
+
+Libvirt's debug logs only ever have passwords and disk encryption secrets in
+encrypted form without the key being part of the log. There's one notable
+exception, that ``VNC/SPICE`` passwords can be found in the logs.
+
+In case you decide to mask information you consider sensitive from the posted
+debug logs, make sure that the masking doesn't introduce ambiguity.

docs/kbase/index.rst

@@ -55,6 +55,9 @@ Usage
 `Memory devices <memorydevices.html>`__
    Memory devices and their use
 
+`Snapshots <snapshots.html>`__
+    Details about snapshotting a VM
+
 
 Internals / Debugging
 ---------------------

docs/kbase/meson.build

@@ -18,6 +18,7 @@ docs_kbase_files = [
   'rpm-deployment',
   's390_protected_virt',
   'secureusage',
+  'snapshots',
   'systemtap',
   'virtiofs',
 ]

docs/kbase/snapshots.rst

@@ -0,0 +1,48 @@
+=========
+Snapshots
+=========
+
+.. contents::
+
+Manual storage snapshotting
+===========================
+
+Certain use cases such as block storage on LVM or disks backed via storage
+exported through the ``vhost-user-blk`` protocol may require that snapshots are
+done in conjunction with the storage provider which is not managed by **libvirt**.
+
+To achieve this such disks can use ``snapshot`` mode ``manual``. When a snapshot
+has a disk in manual mode the following happens:
+
+ #. ``libvirt`` takes snapshot of the VM memory if requested
+
+   #. If a live snapshot is requested (``VIR_DOMAIN_SNAPSHOT_CREATE_LIVE``) the
+      VM runs until the memory snapshot phase completes and is then paused.
+   #. Otherwise the VM is paused right away.
+
+ #. Snapshot of disks which are marked for external snapsot is executed
+ #. The API return success, the VM is paused.
+ #. The user snapshots the externally managed storage
+ #. The user resumes the execution of the VM (``virsh resume $VM``)
+
+Overview of manual snapshots
+----------------------------
+
+Manual snapshot of a disk is requested by setting the ``snapshot`` property to
+``manual`` in the snapshot XML ::
+
+  <domainsnapshot>
+    <memory file='/path/to/memory/img'/>
+    <disks>
+      <disk name='vda' snapshot='manual'/>
+      <disk name='vdb' snapshot='external'/>
+      <disk name='vdc' snapshot='no'/>
+    </disks>
+  </domainsnapshot>
+
+or ``--diskspec vda,snapshot=manual`` when using ``virsh snapshot-create-as``::
+
+  $ virsh snapshot-create-as  --diskspec vda,snapshot=manual \
+                              --diskspec vdb,snapshot=external \
+                              --diskspec vdc,snapshot=no $VM \
+                              --memspec file=/path/to/memory/img

docs/macos.rst

@@ -0,0 +1,44 @@
+.. role:: since
+
+=============
+macOS support
+=============
+
+.. contents::
+
+Libvirt works both as client (for most drivers) and server (for the
+`QEMU driver <drvqemu.html>`__) on macOS.
+
+:since:`Since 8.1.0`, the "hvf" domain type can be used to run
+hardware-accelerated VMs on macOS via
+`Hypervisor.framework <https://developer.apple.com/documentation/hypervisor>`__.
+QEMU version 2.12 or newer is needed for this to work.
+
+
+Installation
+============
+
+libvirt client (virsh), server (libvirtd) and development headers can be
+installed from `Homebrew <https://brew.sh>`__:
+
+::
+
+   brew install libvirt
+
+
+Running libvirtd locally
+========================
+
+The server can be started manually:
+
+::
+
+   $ libvirtd
+
+or on system boot:
+
+::
+
+   $ brew services start libvirt
+
+Once started, you can use virsh as you would on Linux.

docs/manpages/index.rst

@@ -41,6 +41,7 @@ Tools
 * `virt-admin(1) <virt-admin.html>`__ - daemon administration interface
 * `virsh(1) <virsh.html>`__ - management user interface
 * `virt-qemu-run(1) <virt-qemu-run.html>`__ - run standalone QEMU instances
+* `libvirt-guests(8) <libvirt-guests.html>`__ - suspend/resume running libvirt guests
 
 Key codes
 =========

docs/manpages/libvirt-guests.rst

@@ -0,0 +1,151 @@
+==============
+libvirt-guests
+==============
+
+-------------------------------------
+suspend/resume running libvirt guests
+-------------------------------------
+
+:Manual section: 8
+:Manual group: Virtualization Support
+
+.. contents::
+
+SYNOPSIS
+========
+
+``libvirt-guests`` *COMMAND*
+
+
+DESCRIPTION
+===========
+
+``libvirt-guests`` is a service that can be used to coordinate guest and host
+lifecycle actions. By default, ``libvirt-guests`` will suspend running guests
+when the host shuts down, and restore them to their pre-shutdown state when
+the host reboots.
+
+``libvirt-guests`` is typically under control of systemd. When
+``libvirt-guests.service`` is enabled, systemd will call ``libvirt-guests``
+with the ``start`` *COMMAND* when the host boots. Conversely, systemd will call
+``libvirt-guests`` with the ``stop`` *COMMAND* when the host shuts down.
+
+``libvirt-guests`` can be used directly. In addition to the ``start`` and
+``stop`` *COMMAND*\s, it also supports ``status``, ``restart``, ``condrestart``,
+``try-restart``, ``reload``, ``force-reload``, ``gueststatus``, and
+``shutdown`` *COMMAND*\s.
+
+
+FILES
+=====
+
+``libvirt-guests`` defines several variables to control service behavior.
+The default value of these variables can be overridden in:
+
+* ``@SYSCONFDIR@/sysconfig/libvirt-guests``
+
+The following variables are supported:
+
+- URIS=default
+
+  URIs to check for running guests. Example:
+  ``URIS='default xen:///system xen+tcp://host/system lxc:///system'``
+
+- ON_BOOT=start
+
+  Action taken on host boot
+
+  * start
+
+    All guests which were running on shutdown are started on boot regardless
+    of their autostart settings
+
+  * ignore
+
+    ``libvirt-guests`` won't start any guest on boot, however, guests marked
+    as autostart will still be automatically started by libvirtd
+
+- START_DELAY=0
+
+  Number of seconds to wait between each guest start. Set to 0 to allow parallel
+  startup.
+
+- ON_SHUTDOWN=suspend
+
+  Action taken on host shutdown
+
+  * suspend
+
+    All running guests are suspended using virsh managedsave
+
+  * shutdown
+
+    All running guests are asked to shutdown. Please be careful with this
+    settings since there is no way to distinguish between a guest which is
+    stuck or ignores shutdown requests and a guest which just needs a long
+    time to shutdown. When setting ON_SHUTDOWN=shutdown, you must also set
+    SHUTDOWN_TIMEOUT to a value suitable for your guests.
+
+- PARALLEL_SHUTDOWN=0
+
+  Number of guests will be shutdown concurrently, taking effect when
+  "ON_SHUTDOWN" is set to "shutdown". If Set to 0, guests will be shutdown one
+  after another. Number of guests on shutdown at any time will not exceed number
+  set in this variable.
+
+- SHUTDOWN_TIMEOUT=300
+
+  Number of seconds we're willing to wait for a guest to shut down. If parallel
+  shutdown is enabled, this timeout applies as a timeout for shutting down all
+  guests on a single URI defined in the variable URIS. If this is 0, then there
+  is no time out (use with caution, as guests might not respond to a shutdown
+  request). The default value is 300 seconds (5 minutes).
+
+- BYPASS_CACHE=0
+
+  If non-zero, try to bypass the file system cache when saving and
+  restoring guests, even though this may give slower operation for
+  some file systems.
+
+- SYNC_TIME=0
+
+  If non-zero, try to sync guest time on domain resume. Be aware, that
+  this requires guest agent with support for time synchronization
+  running in the guest. By default, this functionality is turned off.
+
+
+BUGS
+====
+
+Please report all bugs you discover.  This should be done via either:
+
+#. the mailing list
+
+   `https://libvirt.org/contact.html <https://libvirt.org/contact.html>`_
+
+#. the bug tracker
+
+   `https://libvirt.org/bugs.html <https://libvirt.org/bugs.html>`_
+
+Alternatively, you may report bugs to your software distributor / vendor.
+
+
+AUTHORS
+=======
+
+Please refer to the AUTHORS file distributed with libvirt.
+
+
+LICENSE
+=======
+
+``libvirt-guests`` is distributed under the terms of the GNU LGPL v2.1+.
+This is free software; see the source for copying conditions. There
+is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE
+
+
+SEE ALSO
+========
+
+libvirtd(8), `https://libvirt.org/ <https://libvirt.org/>`_

docs/manpages/meson.build

@@ -21,6 +21,7 @@ docs_man_files = [
   { 'name': 'virt-qemu-run', 'section': '1', 'install': conf.has('WITH_QEMU') },
   { 'name': 'virt-xml-validate', 'section': '1', 'install': true },
 
+  { 'name': 'libvirt-guests', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },
   { 'name': 'libvirtd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },
   { 'name': 'virt-sanlock-cleanup', 'section': '8', 'install': conf.has('WITH_SANLOCK') },
   { 'name': 'virt-ssh-helper', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },

docs/manpages/virsh.rst

@@ -1455,7 +1455,7 @@ create
 ::
 
    create FILE [--console] [--paused] [--autodestroy]
-      [--pass-fds N,M,...] [--validate]
+      [--pass-fds N,M,...] [--validate] [--reset-nvram]
 
 Create a domain from an XML <file>. Optionally, *--validate* option can be
 passed to validate the format of the input XML file against an internal RNG
@@ -1478,6 +1478,9 @@ of open file descriptors which should be pass on into the guest. The
 file descriptors will be re-numbered in the guest, starting from 3. This
 is only supported with container based virtualization.
 
+If *--reset-nvram* is specified, any existing NVRAM file will be deleted
+and re-initialized from its pristine template.
+
 **Example:**
 
 #. prepare a template from an existing domain (skip directly to 3a if writing
@@ -1714,13 +1717,16 @@ domdirtyrate-calc
 ::
 
    domdirtyrate-calc <domain> [--seconds <sec>]
+      --mode=[page-sampling | dirty-bitmap | dirty-ring]
 
 Calculate an active domain's memory dirty rate which may be expected by
 user in order to decide whether it's proper to be migrated out or not.
 The ``seconds`` parameter can be used to calculate dirty rate in a
 specific time which allows 60s at most now and would be default to 1s
-if missing. The calculated dirty rate information is available by calling
+if missing. These three *page-sampling, dirty-bitmap, dirty-ring* modes
-'domstats --dirtyrate'.
+are mutually exclusive and alternative when specify calculation mode,
+*page-sampling* is the default mode if missing. The calculated dirty
+rate information is available by calling 'domstats --dirtyrate'.
 
 
 domdisplay
@@ -2768,11 +2774,14 @@ Note that this command requires a guest agent to be configured and running in
 the domain's guest OS.
 
 When run without any arguments, this command prints all information types that
-are supported by the guest agent. You can limit the types of information that
+are supported by the guest agent at that point, omitting unavailable ones.
-are returned by specifying one or more flags.  If a requested information
+Success is always reported in this case.
-type is not supported, the processes will provide an exit code of 1.
+
-Available information types flags are *--user*, *--os*,
+You can limit the types of information that are returned by specifying one or
+more flags.  Available information types flags are *--user*, *--os*,
 *--timezone*, *--hostname*, *--filesystem*, *--disk* and *--interface*.
+If an explicitly requested information type is not supported by the guest agent
+at that point, the processes will provide an exit code of 1.
 
 Note that depending on the hypervisor type and the version of the guest agent
 running within the domain, not all of the following information may be
@@ -3733,7 +3742,7 @@ restore
 ::
 
    restore state-file [--bypass-cache] [--xml file]
-      [{--running | --paused}]
+      [{--running | --paused}] [--reset-nvram]
 
 Restores a domain from a ``virsh save`` state file. See *save* for more info.
 
@@ -3751,6 +3760,9 @@ save image to decide between running or paused; passing either the
 *--running* or *--paused* flag will allow overriding which state the
 domain should be started in.
 
+If *--reset-nvram* is specified, any existing NVRAM file will be deleted
+and re-initialized from its pristine template.
+
 ``Note``: To avoid corrupting file system contents within the domain, you
 should not reuse the saved state file for a second ``restore`` unless you
 have also reverted all storage volumes back to the same contents as when
@@ -4347,7 +4359,7 @@ start
 
    start domain-name-or-uuid [--console] [--paused]
       [--autodestroy] [--bypass-cache] [--force-boot]
-      [--pass-fds N,M,...]
+      [--pass-fds N,M,...] [--reset-nvram]
 
 Start a (previously defined) inactive domain, either from the last
 ``managedsave`` state, or via a fresh boot if no managedsave state is
@@ -4366,6 +4378,9 @@ of open file descriptors which should be pass on into the guest. The
 file descriptors will be re-numbered in the guest, starting from 3. This
 is only supported with container based virtualization.
 
+If *--reset-nvram* is specified, any existing NVRAM file will be deleted
+and re-initialized from its pristine template.
+
 
 suspend
 -------
@@ -7349,7 +7364,8 @@ snapshot-revert
 
 ::
 
-   snapshot-revert domain {snapshot | --current} [{--running | --paused}] [--force]
+   snapshot-revert domain {snapshot | --current} [{--running | --paused}]
+      [--force] [--reset-nvram]
 
 Revert the given domain to the snapshot specified by *snapshot*, or to
 the current snapshot with *--current*.  Be aware
@@ -7395,6 +7411,9 @@ requires the use of *--force* to proceed:
     likely cause extensive filesystem corruption or crashes due to swap content
     mismatches when run.
 
+If *--reset-nvram* is specified, any existing NVRAM file will be deleted
+and re-initialized from its pristine template.
+
 
 snapshot-delete
 ---------------
@@ -7878,7 +7897,8 @@ qemu-monitor-command
 
 ::
 
-   qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] } command...
+   qemu-monitor-command domain { [--hmp] | [--pretty] [--return-value] }
+       [--pass-fds N,M,...] command...
 
 Send an arbitrary monitor command *command* to domain *domain* through the
 QEMU monitor.  The results of the command will be printed on stdout.
@@ -7911,6 +7931,9 @@ extracted rather than passing through the full reply from QEMU.
 If *--hmp* is passed, the command is considered to be a human monitor command
 and libvirt will automatically convert it into QMP and convert the result back.
 
+If *--pass-fds* is specified, the argument is a comma separated list
+of open file descriptors which should be passed on to qemu along with the
+command.
 
 qemu-agent-command
 ------------------

docs/manpages/virt-admin.rst

@@ -55,7 +55,7 @@ The ``virt-admin`` program understands the following *OPTIONS*.
 ``-c``, ``--connect`` *URI*
 
 Connect to the specified *URI*, as if by the ``connect`` command,
-instead of the default connection.
+instead of the default connection. See `NOTES`_.
 
 ``-d``, ``--debug`` *LEVEL*
 
@@ -90,12 +90,15 @@ virt-admin is coming from.
 NOTES
 =====
 
-Running ``virt-admin`` requires root privileges due to the
+The ``virt-admin`` supports both the monolithic ``libvirtd`` daemon and the
-communications channels used to talk to the daemon. Consider changing the
+`modular daemons <https://www.libvirt.org/daemons.html#modular-driver-daemons>`__
-*unix_sock_group* ownership setting to grant access to specific set of users
+whichever is in use by your system. The connection *URI* used with
-or modifying *unix_sock_rw_perms* permissions. Daemon configuration file
+``-c/--connect`` or the `connect`_ command is based on the name of the
-provides more information about setting permissions.
+controlled daemon e.g.: ``virtqemud:///system``, ``libvirtd:///system``.
 
+Running ``virt-admin`` requires root privileges when communicating with the
+system instance of a daemon (*URI* ending in ``/system``) due to the
+communications channels used to talk to the daemon.
 
 GENERIC COMMANDS
 ================
@@ -198,6 +201,8 @@ If *LIBVIRT_ADMIN_DEFAULT_URI* or *uri_default* (see below) were set,
 active connection is executed. Note that this only applies if there is no
 connection at all or there is an inactive one.
 
+See `NOTES`_ on picking the correct *URI* corresponding to a libvirt daemon.
+
 To find the currently used URI, check the *uri* command documented below.
 
 

docs/meson.build

@@ -19,16 +19,10 @@ docs_assets = [
 
 docs_html_in_files = [
   '404',
-  'bugs',
   'cgroups',
-  'contact',
-  'contribute',
   'csharp',
   'dbus',
-  'devguide',
   'docs',
-  'downloads',
-  'drivers',
   'drvbhyve',
   'drvesx',
   'drvhyperv',
@@ -42,77 +36,81 @@ docs_html_in_files = [
   'drvvirtuozzo',
   'drvvmware',
   'drvxen',
-  'errors',
   'firewall',
+  'format',
   'formatcaps',
   'formatdomaincaps',
-  'format',
   'formatnetwork',
   'formatnetworkport',
   'formatnode',
   'formatnwfilter',
-  'formatsecret',
-  'formatsnapshot',
   'formatstoragecaps',
   'formatstorageencryption',
-  'goals',
-  'governance',
   'hooks',
   'index',
   'internals',
   'java',
   'logging',
-  'nss',
-  'pci-hotplug',
   'php',
   'python',
   'remote',
-  'securityprocess',
   'storage',
-  'strategy',
-  'support',
-  'testapi',
-  'testsuites',
-  'testtck',
   'tlscerts',
   'uri',
-  'virshcmdref',
   'windows',
 ]
 
 docs_rst_files = [
   'aclpolkit',
   'advanced-tests',
-  'api_extension',
   'api',
+  'api_extension',
   'apps',
   'auditlog',
   'auth',
-  'bindings',
   'best-practices',
+  'bindings',
+  'bugs',
   'ci',
   'coding-style',
   'committer-guidelines',
   'compiling',
+  'contact',
+  'contribute',
   'daemons',
-  'developer-tooling',
+  'downloads',
-  'drvqemu',
+  'drivers',
   'drvch',
+  'drvqemu',
+  'errors',
   'formatbackup',
   'formatcheckpoint',
   'formatdomain',
+  'formatsecret',
+  'formatsnapshot',
   'formatstorage',
   'glib-adoption',
+  'goals',
+  'governance',
   'hacking',
   'libvirt-go',
   'libvirt-go-xml',
+  'macos',
   'migration',
   'newreposetup',
+  'nss',
   'pci-addresses',
+  'pci-hotplug',
   'platforms',
   'programming-languages',
+  'securityprocess',
+  'strategy',
   'styleguide',
   'submitting-patches',
+  'support',
+  'testapi',
+  'testsuites',
+  'testtck',
 ]
 
 # list of web targets to build for docs/web rule
@@ -132,7 +130,7 @@ aclperms_gen = custom_target(
 )
 
 docs_timestamp = run_command(
-  python3_prog, meson_timestamp_prog.path(), env: runutf8
+  python3_prog, meson_timestamp_prog.path(), env: runutf8, check: true,
 ).stdout().strip()
 
 site_xsl = files('site.xsl')
@@ -171,6 +169,47 @@ docs_lxc_api_xml = docs_api_generated[1]
 docs_qemu_api_xml = docs_api_generated[2]
 docs_admin_api_xml = docs_api_generated[3]
 
+docs_programs_groups = [
+  { 'name': 'rst2html5', 'prog': [ 'rst2html5', 'rst2html5.py', 'rst2html5-3' ] },
+  { 'name': 'rst2man', 'prog': [ 'rst2man', 'rst2man.py', 'rst2man-3' ] },
+]
+
+foreach item : docs_programs_groups
+  prog = find_program(item.get('prog'), dirs: libvirt_sbin_path)
+  varname = item.get('name').underscorify()
+  conf.set_quoted(varname.to_upper(), prog.path())
+  set_variable('@0@_prog'.format(varname), prog)
+endforeach
+
+# There are two versions of rst2html5 in the wild: one is the version
+# coming from the docutils package, and the other is the one coming
+# from the rst2html5 package. These versions are subtly different,
+# and the libvirt documentation can only be successfully generated
+# using the docutils version. Every now and then, users will report
+# build failures that can be traced back to having the wrong version
+# installed.
+#
+# The only reliable way to tell the two binaries apart seems to be
+# looking look at their version information: the docutils version
+# will report
+#
+#   rst2html5 (Docutils ..., Python ..., on ...)
+#
+# whereas the rst2html5 version will report
+#
+#   rst2html5 ... (Docutils ..., Python ..., on ...)
+#
+# with the additional bit of information being the version number for
+# the rst2html5 package itself.
+#
+# Use this knowledge to detect the version that we know doesn't work
+# for building libvirt and reject it
+rst2html5_version = run_command(rst2html5_prog, '--version', check: true)
+rst2html5_version = rst2html5_version.stdout().split(' ')
+if rst2html5_version[1] != '(Docutils'
+  error('Please uninstall the rst2html5 package and install the docutils package')
+endif
+
 docs_rst2html5_gen = generator(
   rst2html5_prog,
   output: '@BASENAME@.html.in',
@@ -294,8 +333,6 @@ subdir('js')
 subdir('kbase')
 subdir('logos')
 subdir('manpages')
-subdir('schemas')
-
 
 foreach file : docs_assets
   # This hack enables us to view the web pages

docs/nss.html.in

@@ -1,189 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Libvirt NSS module</h1>
-
-    <ul id="toc"></ul>
-
-    <p>
-    When it comes to managing guests and executing commands inside them, logging
-    into guest operating system and doing the job is convenient. Users are used
-    to ssh in this case. Ideally:
-    </p>
-
-    <code>ssh user@virtualMachine</code>
-
-    <p>
-    would be nice. But depending on virtual network configuration it might not
-    be always possible. For instance, when using libvirt NATed network it's
-    dnsmasq (spawned by libvirt) who assigns IP addresses to domains. But by
-    default, the dnsmasq process is then not consulted when it comes to host
-    name translation.  Users work around this problem by configuring their
-    libvirt network to assign static IP addresses and maintaining
-    <code>/etc/hosts</code> file in sync. But this puts needless burden onto
-    users. This is where NSS module comes handy.
-    </p>
-
-    <h2><a id="Installation">Installation</a></h2>
-
-    <p>
-    Installing the module is really easy:
-    </p>
-
-<pre>
-# yum install libvirt-nss
-</pre>
-
-    <h2><a id="Configuration">Configuration</a></h2>
-
-    <p>
-    Enabling the module is really easy. Just add <b>libvirt</b> into
-    <code>/etc/nsswitch.conf</code> file. For instance:
-    </p>
-
-<pre>
-$ cat /etc/nsswitch.conf
-# /etc/nsswitch.conf:
-passwd:      compat
-shadow:      compat
-group:       compat
-hosts:       files libvirt dns
-# ...
-</pre>
-
-    <p>
-    So, in this specific case, whenever ssh program is looking up the host user
-    is trying to connect to, <b>files</b> module is consulted first (which
-    boils down to looking up the host name in <code>/etc/hosts</code> file), if
-    not found <b>libvirt</b> module is consulted then. The DNS is the last
-    effort then, if none of the previous modules matched the host in question.
-    Therefore users should consider the order in which they want the modules to
-    lookup given host name.
-    </p>
-
-    <h2><a id="Sources">Sources of information</a></h2>
-
-    <p>
-    As of <code>v3.0.0</code> release, libvirt offers two NSS modules
-    implementing two different methods of hostname translation. The first and
-    older method is implemented by <code>libvirt</code> plugin and
-    basically looks up the hostname to IP address translation in DHCP server
-    records. Therefore this is dependent on hostname provided by guests. Thing
-    is, not all the guests out there provide one in DHCP transactions, or not
-    every sysadmin out there believes all the guests. Hence libvirt implements
-    second method in <code>libvirt_guest</code> module which does libvirt guest
-    name to IP address translation (regardless of hostname set in the guest).
-    </p>
-
-    <p>
-    To enable either of the modules put their name into the
-    <code>nsswitch.conf</code> file. For instance, to enable
-    <code>libvirt_guest</code> module:
-    </p>
-
-<pre>
-$ cat /etc/nsswitch.conf
-# /etc/nsswitch.conf:
-hosts:       files libvirt_guest dns
-# ...
-</pre>
-    <p>Or users can enable both at the same time:</p>
-<pre>
-$ cat /etc/nsswitch.conf
-# /etc/nsswitch.conf:
-hosts:       files libvirt libvirt_guest dns
-# ...
-</pre>
-
-    <p>
-    This configuration will mean that if hostname is not found by the
-    <code>libvirt</code> module (e.g. because a guest did not sent hostname
-    during DHCP transaction), the <code>libvirt_guest</code> module is
-    consulted (and if the hostname matches libvirt guest name it will be
-    resolved).
-    </p>
-
-    <h2><a id="Internals">How does it work?</a></h2>
-
-    <p>
-    Whenever an Unix process wants to do a host name translation
-    <a href="https://linux.die.net/man/3/gethostbyname"><code>gethostbyname()</code></a>
-    or some variant of it is called. This is a glibc function that takes a
-    string containing the host name, crunch it and produces a list of IP
-    addresses assigned to that host. Now, glibc developers made a really good
-    decision when implementing the internals of the function when they decided
-    to make the function pluggable. Since there can be several sources for the
-    records (e.g. <code>/etc/hosts</code> file, DNS, LDAP, etc.) it would not
-    make much sense to create one big implementation containing all possible
-    cases. What they have done instead is this pluggable mechanism. Small
-    plugins implementing nothing but specific technology for lookup process are
-    provided and the function then calls those plugins. There is just one
-    configuration file that instructs the lookup function in which order should
-    the plugins be called and which plugins should be loaded. For more info
-    reading <a href="https://en.wikipedia.org/wiki/Name_Service_Switch">wiki
-    page</a> is recommended.
-    </p>
-
-    <p>
-    And this is point where libvirt comes in. Libvirt provides plugin for the
-    NSS ecosystem. For some time now libvirt keeps a list of assigned IP
-    addresses for libvirt networks. The NSS plugin does no more than search the
-    list trying to find matching record for given host name. When found,
-    matching IP address is returned to the caller. If not found, translation
-    process continues with the next plugin configured. At this point it is
-    important to stress the order in which plugins are called. Users should be
-    aware that a hostname might match in multiple plugins and right after first
-    match, translation process is terminated and no other plugin is consulted.
-    Therefore, if there are two different records for the same host name users
-    should carefully chose the lookup order.
-    </p>
-
-    <h2><a id="Limitations">Limitations</a></h2>
-
-    <ol>
-      <li>The <code>libvirt</code> NSS module matches only hostnames provided by guest.
-        If the libvirt name and one advertised by guest differs, the latter is
-        matched. However, as of <code>v3.0.0</code> there are two libvirt NSS modules
-        translating both hostnames provided by guest and libvirt guest names.</li>
-      <li>The module works only in that cases where IP addresses are assigned by
-        dnsmasq spawned by libvirt. Libvirt NATed networks are typical
-        example.</li>
-    </ol>
-
-    <p>
-    <i>The following paragraph describes implementation limitation of the
-    <code>libvirt</code> NSS module.</i>
-    These limitation are result of libvirt's internal implementation. While
-    libvirt can report IP addresses regardless of their origin, a public API
-    must be used to obtain those. However, for the API a connection object is
-    required. Doing that for every name translation request would be too
-    costly.  Fortunately, libvirt spawns dnsmasq for NATed networks. Not only
-    that, it provides small executable that on each IP address space change
-    updates an internal list of addresses thus keeping it in sync. The NSS
-    module then merely consults the list trying to find the match. Users can
-    view the list themselves:
-    </p>
-
-<pre>
-virsh net-dhcp-leases $network
-</pre>
-
-    <p>
-    where <code>$network</code> iterates through all running networks. So the module
-    does merely the same as
-    </p>
-
-<pre>
-virsh domifaddr --source lease $domain
-</pre>
-
-    <p>
-    If there's no record for either of the aforementioned commands, it's
-    very likely that NSS module won't find anything and vice versa.
-    As of <code>v3.0.0</code> libvirt provides <code>libvirt_guest</code> NSS
-    module that doesn't have this limitation. However, the statement is still
-    true for the <code>libvirt</code> NSS module.
-    </p>
-  </body>
-</html>

docs/nss.rst

@@ -0,0 +1,154 @@
+==================
+Libvirt NSS module
+==================
+
+.. contents::
+
+When it comes to managing guests and executing commands inside them, logging
+into guest operating system and doing the job is convenient. Users are used to
+ssh in this case. Ideally:
+
+``ssh user@virtualMachine``
+
+would be nice. But depending on virtual network configuration it might not be
+always possible. For instance, when using libvirt NATed network it's dnsmasq
+(spawned by libvirt) who assigns IP addresses to domains. But by default, the
+dnsmasq process is then not consulted when it comes to host name translation.
+Users work around this problem by configuring their libvirt network to assign
+static IP addresses and maintaining ``/etc/hosts`` file in sync. But this puts
+needless burden onto users. This is where NSS module comes handy.
+
+Installation
+------------
+
+Installing the module is really easy:
+
+::
+
+   # yum install libvirt-nss
+
+Configuration
+-------------
+
+Enabling the module is really easy. Just add **libvirt** into
+``/etc/nsswitch.conf`` file. For instance:
+
+::
+
+   $ cat /etc/nsswitch.conf
+   # /etc/nsswitch.conf:
+   passwd:      compat
+   shadow:      compat
+   group:       compat
+   hosts:       files libvirt dns
+   # ...
+
+So, in this specific case, whenever ssh program is looking up the host user is
+trying to connect to, **files** module is consulted first (which boils down to
+looking up the host name in ``/etc/hosts`` file), if not found **libvirt**
+module is consulted then. The DNS is the last effort then, if none of the
+previous modules matched the host in question. Therefore users should consider
+the order in which they want the modules to lookup given host name.
+
+Sources of information
+----------------------
+
+As of ``v3.0.0`` release, libvirt offers two NSS modules implementing two
+different methods of hostname translation. The first and older method is
+implemented by ``libvirt`` plugin and basically looks up the hostname to IP
+address translation in DHCP server records. Therefore this is dependent on
+hostname provided by guests. Thing is, not all the guests out there provide one
+in DHCP transactions, or not every sysadmin out there believes all the guests.
+Hence libvirt implements second method in ``libvirt_guest`` module which does
+libvirt guest name to IP address translation (regardless of hostname set in the
+guest).
+
+To enable either of the modules put their name into the ``nsswitch.conf`` file.
+For instance, to enable ``libvirt_guest`` module:
+
+::
+
+   $ cat /etc/nsswitch.conf
+   # /etc/nsswitch.conf:
+   hosts:       files libvirt_guest dns
+   # ...
+
+Or users can enable both at the same time:
+
+::
+
+   $ cat /etc/nsswitch.conf
+   # /etc/nsswitch.conf:
+   hosts:       files libvirt libvirt_guest dns
+   # ...
+
+This configuration will mean that if hostname is not found by the ``libvirt``
+module (e.g. because a guest did not sent hostname during DHCP transaction), the
+``libvirt_guest`` module is consulted (and if the hostname matches libvirt guest
+name it will be resolved).
+
+How does it work?
+-----------------
+
+Whenever an Unix process wants to do a host name translation
+`gethostbyname() <https://linux.die.net/man/3/gethostbyname>`__ or some variant
+of it is called. This is a glibc function that takes a string containing the
+host name, crunch it and produces a list of IP addresses assigned to that host.
+Now, glibc developers made a really good decision when implementing the
+internals of the function when they decided to make the function pluggable.
+Since there can be several sources for the records (e.g. ``/etc/hosts`` file,
+DNS, LDAP, etc.) it would not make much sense to create one big implementation
+containing all possible cases. What they have done instead is this pluggable
+mechanism. Small plugins implementing nothing but specific technology for lookup
+process are provided and the function then calls those plugins. There is just
+one configuration file that instructs the lookup function in which order should
+the plugins be called and which plugins should be loaded. For more info reading
+`wiki page <https://en.wikipedia.org/wiki/Name_Service_Switch>`__ is
+recommended.
+
+And this is point where libvirt comes in. Libvirt provides plugin for the NSS
+ecosystem. For some time now libvirt keeps a list of assigned IP addresses for
+libvirt networks. The NSS plugin does no more than search the list trying to
+find matching record for given host name. When found, matching IP address is
+returned to the caller. If not found, translation process continues with the
+next plugin configured. At this point it is important to stress the order in
+which plugins are called. Users should be aware that a hostname might match in
+multiple plugins and right after first match, translation process is terminated
+and no other plugin is consulted. Therefore, if there are two different records
+for the same host name users should carefully chose the lookup order.
+
+Limitations
+-----------
+
+#. The ``libvirt`` NSS module matches only hostnames provided by guest. If the
+   libvirt name and one advertised by guest differs, the latter is matched.
+   However, as of ``v3.0.0`` there are two libvirt NSS modules translating both
+   hostnames provided by guest and libvirt guest names.
+#. The module works only in that cases where IP addresses are assigned by
+   dnsmasq spawned by libvirt. Libvirt NATed networks are typical example.
+
+*The following paragraph describes implementation limitation of the ``libvirt``
+NSS module.* These limitation are result of libvirt's internal implementation.
+While libvirt can report IP addresses regardless of their origin, a public API
+must be used to obtain those. However, for the API a connection object is
+required. Doing that for every name translation request would be too costly.
+Fortunately, libvirt spawns dnsmasq for NATed networks. Not only that, it
+provides small executable that on each IP address space change updates an
+internal list of addresses thus keeping it in sync. The NSS module then merely
+consults the list trying to find the match. Users can view the list themselves:
+
+::
+
+   virsh net-dhcp-leases $network
+
+where ``$network`` iterates through all running networks. So the module does
+merely the same as
+
+::
+
+   virsh domifaddr --source lease $domain
+
+If there's no record for either of the aforementioned commands, it's very likely
+that NSS module won't find anything and vice versa. As of ``v3.0.0`` libvirt
+provides ``libvirt_guest`` NSS module that doesn't have this limitation.
+However, the statement is still true for the ``libvirt`` NSS module.

docs/page.xsl

@@ -187,7 +187,7 @@
             </div>
           </xsl:if>
           <div id="conduct">
-            Participants in the libvirt project agree to abide by <a href="{$href_base}governance.html#codeofconduct">the project code of conduct</a>
+            Participants in the libvirt project agree to abide by <a href="{$href_base}governance.html#code-of-conduct">the project code of conduct</a>
           </div>
           <br class="clear"/>
         </div>
@@ -215,11 +215,11 @@
     </xsl:element>
   </xsl:template>
 
-  <xsl:template match="text()" mode="copy">
+  <xsl:template match="text()" mode="copy" priority="0">
     <xsl:value-of select="."/>
   </xsl:template>
 
-  <xsl:template match="node()" mode="copy">
+  <xsl:template match="*" mode="copy">
     <xsl:element name="{name()}">
       <xsl:copy-of select="./@*"/>
       <xsl:apply-templates mode="copy" />

docs/pci-hotplug.html.in

@@ -1,185 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>PCI topology and hotplug</h1>
-
-    <ul id="toc"></ul>
-
-    <p>
-      Perhaps surprisingly, most libvirt guests support only limited PCI
-      device hotplug out of the box, or even none at all.
-    </p>
-    <p>
-      The reason for this apparent limitation is the fact that each
-      hotplugged PCI device might require additional PCI controllers to
-      be added to the guest. Since most PCI controllers can't be
-      hotplugged, they need to be added before the guest is started;
-      however, libvirt has no way of knowing in advance how many devices
-      will be hotplugged during the guest's lifetime, thus making it
-      impossible to automatically provide the right amount of PCI
-      controllers: any arbitrary number would end up being too big
-      for some users, and too small for others.
-    </p>
-    <p>
-      Ultimately, the user is the only one who knows how much the guest
-      will need to grow dynamically, so the responsibility of planning
-      a suitable PCI topology in advance falls on them.
-    </p>
-    <p>
-      This document aims at providing all the information needed to
-      successfully plan the PCI topology of a guest. Note that the
-      details can vary a lot between architectures and even machine
-      types, hence the way it's organized.
-    </p>
-
-    <h2><a id="x86_64">x86_64 architecture</a></h2>
-
-    <h3><a id="x86_64-q35">q35 machine type</a></h3>
-
-    <p>
-      This is a PCI Express native machine type. The default PCI topology
-      looks like
-    </p>
-
-<pre>
-&lt;controller type='pci' index='0' model='pcie-root'/&gt;
-&lt;controller type='pci' index='1' model='pcie-root-port'&gt;
-  &lt;model name='pcie-root-port'/&gt;
-  &lt;target chassis='1' port='0x10'/&gt;
-  &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/&gt;
-&lt;/controller&gt;</pre>
-
-    <p>
-      and supports hotplugging a single PCI Express device, either
-      emulated or assigned from the host.
-    </p>
-    <p>
-      If you have a very specific use case, such as the appliances
-      used by <a href="https://libguestfs.org/">libguestfs</a> behind
-      the scenes to access disk images, and this automatically-added
-      <code>pcie-root-port</code> controller ends up being a nuisance,
-      you can prevent libvirt from adding it by manually managing PCI
-      controllers and addresses according to your needs.
-    </p>
-    <p>
-      Slots on the <code>pcie-root</code> controller do not support
-      hotplug, so the device will be hotplugged into the
-      <code>pcie-root-port</code> controller. If you plan to hotplug
-      more than a single PCI Express device, you should add a suitable
-      number of <code>pcie-root-port</code> controllers when defining
-      the guest: for example, add
-    </p>
-
-<pre>
-&lt;controller type='pci' model='pcie-root'/&gt;
-&lt;controller type='pci' model='pcie-root-port'/&gt;
-&lt;controller type='pci' model='pcie-root-port'/&gt;
-&lt;controller type='pci' model='pcie-root-port'/&gt;</pre>
-
-    <p>
-      if you expect to hotplug up to three PCI Express devices,
-      either emulated or assigned from the host. That's all the
-      information you need to provide: libvirt will fill in the
-      remaining details automatically. Note that you need to add
-      the <code>pcie-root</code> controller along with the
-      <code>pcie-root-port</code> controllers or you will get an
-      error.
-    </p>
-    <p>
-      Note that if you're adding PCI controllers to a guest and at
-      the same time you're also adding PCI devices, some of the
-      controllers will be used for the newly-added devices and won't
-      be available for hotplug once the guest has been started.
-    </p>
-    <p>
-      If you expect to hotplug legacy PCI devices, then you will need
-      specialized controllers, since all those mentioned above are
-      intended for PCI Express devices only: add
-    </p>
-
-<pre>
-&lt;controller type='pci' model='pcie-to-pci-bridge'/&gt;</pre>
-
-    <p>
-      and you'll be able to hotplug up to 31 legacy PCI devices,
-      either emulated or assigned from the host, in the slots
-      from 0x01 to 0x1f of the <code>pcie-to-pci-bridge</code> controller.
-    </p>
-
-    <h3><a id="x86_64-i440fx">i440fx (pc) machine type</a></h3>
-
-    <p>
-      This is a legacy PCI native machine type. The default PCI
-      topology looks like
-    </p>
-
-<pre>
-&lt;controller type='pci' index='0' model='pci-root'/&gt;</pre>
-
-    <p>
-      where each of the 31 slots (from 0x01 to 0x1f) on the
-      <code>pci-root</code> controller is hotplug capable and
-      can accept a legacy PCI device, either emulated or
-      assigned from the guest.
-    </p>
-
-    <h2><a id="ppc64">ppc64 architecture</a></h2>
-
-    <h3><a id="ppc64-pseries">pseries machine type</a></h3>
-
-    <p>
-      The default PCI topology for the <code>pseries</code> machine
-      type looks like
-    </p>
-
-<pre>
-&lt;controller type='pci' index='0' model='pci-root'&gt;
-  &lt;model name='spapr-pci-host-bridge'/&gt;
-  &lt;target index='0'/&gt;
-&lt;/controller&gt;</pre>
-
-    <p>
-      The 31 slots, from 0x01 to 0x1f, on a <code>pci-root</code>
-      controller are all hotplug capable and, despite the name
-      suggesting otherwise, starting with QEMU 2.9 all of them
-      can accept PCI Express devices in addition to legacy PCI
-      devices; however, libvirt will only place emulated devices
-      on the default <code>pci-root</code> controller.
-    </p>
-    <p>
-      In order to take advantage of improved error reporting and
-      recovering capabilities, PCI devices assigned from the
-      host need to be isolated by placing each on a separate
-      <code>pci-root</code> controller, which has to be prepared
-      in advance for hotplug to work: for example, add
-    </p>
-
-<pre>
-&lt;controller type='pci' model='pci-root'/&gt;
-&lt;controller type='pci' model='pci-root'/&gt;
-&lt;controller type='pci' model='pci-root'/&gt;</pre>
-
-    <p>
-      if you expect to hotplug up to three PCI devices assigned
-      from the host.
-    </p>
-
-    <h2><a id="aarch64">aarch64 architecture</a></h2>
-
-    <h3><a id="aarch64-virt">mach-virt (virt) machine type</a></h3>
-
-    <p>
-      This machine type mostly behaves the same as the
-      <a href="#x86_64-q35">q35 machine type</a>, so you can just
-      refer to that section for information.
-    </p>
-    <p>
-      The only difference worth mentioning is that using legacy
-      PCI for <code>mach-virt</code> guests is extremely uncommon,
-      so you'll probably never need to add controllers other than
-      <code>pcie-root-port</code>.
-    </p>
-
-  </body>
-</html>

docs/pci-hotplug.rst

@@ -0,0 +1,146 @@
+========================
+PCI topology and hotplug
+========================
+
+.. contents::
+
+Perhaps surprisingly, most libvirt guests support only limited PCI device
+hotplug out of the box, or even none at all.
+
+The reason for this apparent limitation is the fact that each hotplugged PCI
+device might require additional PCI controllers to be added to the guest. Since
+most PCI controllers can't be hotplugged, they need to be added before the guest
+is started; however, libvirt has no way of knowing in advance how many devices
+will be hotplugged during the guest's lifetime, thus making it impossible to
+automatically provide the right amount of PCI controllers: any arbitrary number
+would end up being too big for some users, and too small for others.
+
+Ultimately, the user is the only one who knows how much the guest will need to
+grow dynamically, so the responsibility of planning a suitable PCI topology in
+advance falls on them.
+
+This document aims at providing all the information needed to successfully plan
+the PCI topology of a guest. Note that the details can vary a lot between
+architectures and even machine types, hence the way it's organized.
+
+x86_64 architecture
+-------------------
+
+q35 machine type
+~~~~~~~~~~~~~~~~
+
+This is a PCI Express native machine type. The default PCI topology looks like
+
+::
+
+   <controller type='pci' index='0' model='pcie-root'/>
+   <controller type='pci' index='1' model='pcie-root-port'>
+     <model name='pcie-root-port'/>
+     <target chassis='1' port='0x10'/>
+     <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/>
+   </controller>
+
+and supports hotplugging a single PCI Express device, either emulated or
+assigned from the host.
+
+If you have a very specific use case, such as the appliances used by
+`libguestfs <https://libguestfs.org/>`__ behind the scenes to access disk
+images, and this automatically-added ``pcie-root-port`` controller ends up being
+a nuisance, you can prevent libvirt from adding it by manually managing PCI
+controllers and addresses according to your needs.
+
+Slots on the ``pcie-root`` controller do not support hotplug, so the device will
+be hotplugged into the ``pcie-root-port`` controller. If you plan to hotplug
+more than a single PCI Express device, you should add a suitable number of
+``pcie-root-port`` controllers when defining the guest: for example, add
+
+::
+
+   <controller type='pci' model='pcie-root'/>
+   <controller type='pci' model='pcie-root-port'/>
+   <controller type='pci' model='pcie-root-port'/>
+   <controller type='pci' model='pcie-root-port'/>
+
+if you expect to hotplug up to three PCI Express devices, either emulated or
+assigned from the host. That's all the information you need to provide: libvirt
+will fill in the remaining details automatically. Note that you need to add the
+``pcie-root`` controller along with the ``pcie-root-port`` controllers or you
+will get an error.
+
+Note that if you're adding PCI controllers to a guest and at the same time
+you're also adding PCI devices, some of the controllers will be used for the
+newly-added devices and won't be available for hotplug once the guest has been
+started.
+
+If you expect to hotplug legacy PCI devices, then you will need specialized
+controllers, since all those mentioned above are intended for PCI Express
+devices only: add
+
+::
+
+   <controller type='pci' model='pcie-to-pci-bridge'/>
+
+and you'll be able to hotplug up to 31 legacy PCI devices, either emulated or
+assigned from the host, in the slots from 0x01 to 0x1f of the
+``pcie-to-pci-bridge`` controller.
+
+i440fx (pc) machine type
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a legacy PCI native machine type. The default PCI topology looks like
+
+::
+
+   <controller type='pci' index='0' model='pci-root'/>
+
+where each of the 31 slots (from 0x01 to 0x1f) on the ``pci-root`` controller is
+hotplug capable and can accept a legacy PCI device, either emulated or assigned
+from the guest.
+
+ppc64 architecture
+------------------
+
+pseries machine type
+~~~~~~~~~~~~~~~~~~~~
+
+The default PCI topology for the ``pseries`` machine type looks like
+
+::
+
+   <controller type='pci' index='0' model='pci-root'>
+     <model name='spapr-pci-host-bridge'/>
+     <target index='0'/>
+   </controller>
+
+The 31 slots, from 0x01 to 0x1f, on a ``pci-root`` controller are all hotplug
+capable and, despite the name suggesting otherwise, starting with QEMU 2.9 all
+of them can accept PCI Express devices in addition to legacy PCI devices;
+however, libvirt will only place emulated devices on the default ``pci-root``
+controller.
+
+In order to take advantage of improved error reporting and recovering
+capabilities, PCI devices assigned from the host need to be isolated by placing
+each on a separate ``pci-root`` controller, which has to be prepared in advance
+for hotplug to work: for example, add
+
+::
+
+   <controller type='pci' model='pci-root'/>
+   <controller type='pci' model='pci-root'/>
+   <controller type='pci' model='pci-root'/>
+
+if you expect to hotplug up to three PCI devices assigned from the host.
+
+aarch64 architecture
+--------------------
+
+mach-virt (virt) machine type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This machine type mostly behaves the same as the `q35 machine
+type <#q35-machine-type>`__, so you can just refer to that section for
+information.
+
+The only difference worth mentioning is that using legacy PCI for ``mach-virt``
+guests is extremely uncommon, so you'll probably never need to add controllers
+other than ``pcie-root-port``.

docs/platforms.rst

@@ -42,8 +42,10 @@ The project aims to support the most recent major version at all times. Support
 for the previous major version will be dropped 2 years after the new major
 version is released or when the vendor itself drops support, whichever comes
 first. In this context, third-party efforts to extend the lifetime of a distro
-are not considered, even when they are endorsed by the vendor (eg. Debian LTS).
+are not considered, even when they are endorsed by the vendor (e.g. Debian
-Within each major release, only the most recent minor release is considered.
+LTS); the same is true of repositories that contain packages backported from
+later releases (e.g. Debian backports). Within each major release, only the
+most recent minor release is considered.
 
 For the purposes of identifying supported software versions available on Linux,
 the project will look at CentOS, Debian, Fedora, openSUSE, RHEL, SLES and

docs/remote.html.in

@@ -138,9 +138,9 @@ Blank lines and comments beginning with <code>#</code> are ignored.
         <td> 1 (on) </td>
         <td>
   Listen for secure TLS connections on the public TCP/IP port.
-  Note: it is also necessary to start the server in listening mode by
+  Note: it is also necessary to start the server in listening mode
-  running it with --listen or editing /etc/sysconfig/libvirtd by uncommenting the LIBVIRTD_ARGS="--listen" line
+  by running it with --listen or adding a LIBVIRTD_ARGS="--listen"
-  to cause the server to come up in listening mode whenever it is started.
+  line to /etc/sysconfig/libvirtd.
 </td>
       </tr>
       <tr>

docs/securityprocess.html.in

@@ -1,119 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-
-    <h1>Security Process</h1>
-
-    <ul id="toc"></ul>
-
-    <p>
-      The libvirt project believes in responsible disclosure of
-      security problems, to allow vendors time to prepare and
-      distribute patches for problems ahead of their publication.
-      This page describes how the process works and how to report
-      potential security issues.
-    </p>
-
-    <h2><a id="reporting">Reporting security issues</a></h2>
-
-    <p>
-      In the event that a bug in libvirt is found which is
-      believed to have (potential) security implications there
-      is a dedicated contact to which a bug report / notification
-      should be directed. Send an email with as many details of
-      the problem as possible (ideally with steps to reproduce)
-      to the following email address:
-    </p>
-
-    <pre>
-<a href="mailto:libvirt-security@redhat.com">libvirt-security@redhat.com</a></pre>
-
-    <p>
-      NB. while this email address is backed by a mailing list, it
-      is invitation only and moderated for non-members. As such you
-      will receive an auto-reply indicating the report is held for
-      moderation. Postings by non-members will be approved by a
-      moderator and the reporter copied on any replies.
-    </p>
-
-    <h2><a id="secnotice">Security notices</a></h2>
-
-    <p>
-      Information for all historical security issues is maintained in
-      machine parsable format in the
-      <a href="https://gitlab.com/libvirt/libvirt-security-notice">libvirt-security-notice GIT repository</a> and
-      <a href="https://security.libvirt.org">published online</a>
-      in text, HTML and XML formats. Security notices are published
-      on the <a href="https://libvirt.org/contact.html#email">libvirt-announce mailing list</a>
-      when any embargo is lifted, or as soon as triaged if already
-      public knowledge.
-    </p>
-
-    <h2><a id="seclist">Security team</a></h2>
-
-    <p>
-      The libvirt security team is made up of a subset of the libvirt
-      core development team which covers the various distro maintainers
-      of libvirt, along with nominated security engineers representing
-      the various vendors who distribute libvirt. The team is responsible
-      for analysing incoming reports from users to identify whether a
-      security problem exists and its severity. It then works to produce
-      a fix for all official stable branches of libvirt and coordinate
-      embargo dates between vendors to allow simultaneous release of the
-      fix by all affected parties.
-    </p>
-
-    <p>
-      If you are a security representative of a vendor distributing
-      libvirt and would like to join the security team, send an email
-      to the afore-mentioned security address. Typically an existing
-      member of the security team will have to vouch for your credentials
-      before membership is approved. All members of the security team
-      are <strong>required to respect the embargo policy</strong>
-      described below.
-    </p>
-
-    <h2><a id="embargo">Publication embargo policy</a></h2>
-
-    <p>
-      The libvirt security team operates a policy of
-      <a href="https://en.wikipedia.org/wiki/Responsible_disclosure">responsible disclosure</a>.
-      As such any security issue reported, that is not already publicly disclosed
-      elsewhere, will have an embargo date assigned. Members of the security team agree
-      not to publicly disclose any details of the security issue until the embargo
-      date expires.
-    </p>
-
-    <p>
-      The general aim of the team is to have embargo dates which
-      are two weeks or less in duration. If a problem is identified
-      with a proposed patch for a security issue, requiring further
-      investigation and bug fixing, the embargo clock may be restarted.
-      In exceptional circumstances longer initial embargoes may be
-      negotiated by mutual agreement between members of the security
-      team and other relevant parties to the problem. Any such extended
-      embargoes will aim to be at most one month in duration.
-    </p>
-
-
-    <h2><a id="cve">CVE allocation</a></h2>
-
-    <p>
-      The libvirt security team will associate each security issue with
-      a CVE number. The CVE numbers will usually be allocated by one of
-      the vendor security engineers on the security team.
-    </p>
-
-    <h2><a id="branches">Branch fixing policy</a></h2>
-
-    <p>
-      The libvirt community maintains one or more stable release branches
-      at any given point in time. The security team will aim to publish
-      fixes for GIT master (which will become the next major release) and
-      each currently maintained stable release branch. The distro maintainers
-      will be responsible for backporting the officially published fixes to
-      other release branches where applicable.
-    </p>
-  </body>
-</html>

docs/securityprocess.rst

@@ -0,0 +1,89 @@
+================
+Security Process
+================
+
+.. contents::
+
+The libvirt project believes in responsible disclosure of security problems, to
+allow vendors time to prepare and distribute patches for problems ahead of their
+publication. This page describes how the process works and how to report
+potential security issues.
+
+Reporting security issues
+-------------------------
+
+In the event that a bug in libvirt is found which is believed to have
+(potential) security implications there is a dedicated contact to which a bug
+report / notification should be directed. Send an email with as many details of
+the problem as possible (ideally with steps to reproduce) to the following email
+address:
+
+::
+
+   libvirt-security@redhat.com
+
+NB. while this email address is backed by a mailing list, it is invitation only
+and moderated for non-members. As such you will receive an auto-reply indicating
+the report is held for moderation. Postings by non-members will be approved by a
+moderator and the reporter copied on any replies.
+
+Security notices
+----------------
+
+Information for all historical security issues is maintained in machine parsable
+format in the `libvirt-security-notice GIT
+repository <https://gitlab.com/libvirt/libvirt-security-notice>`__ and
+`published online <https://security.libvirt.org>`__ in text, HTML and XML
+formats. Security notices are published on the `libvirt-announce mailing
+list <https://libvirt.org/contact.html#email>`__ when any embargo is lifted, or
+as soon as triaged if already public knowledge.
+
+Security team
+-------------
+
+The libvirt security team is made up of a subset of the libvirt core development
+team which covers the various distro maintainers of libvirt, along with
+nominated security engineers representing the various vendors who distribute
+libvirt. The team is responsible for analysing incoming reports from users to
+identify whether a security problem exists and its severity. It then works to
+produce a fix for all official stable branches of libvirt and coordinate embargo
+dates between vendors to allow simultaneous release of the fix by all affected
+parties.
+
+If you are a security representative of a vendor distributing libvirt and would
+like to join the security team, send an email to the afore-mentioned security
+address. Typically an existing member of the security team will have to vouch
+for your credentials before membership is approved. All members of the security
+team are **required to respect the embargo policy** described below.
+
+Publication embargo policy
+--------------------------
+
+The libvirt security team operates a policy of `responsible
+disclosure <https://en.wikipedia.org/wiki/Responsible_disclosure>`__. As such
+any security issue reported, that is not already publicly disclosed elsewhere,
+will have an embargo date assigned. Members of the security team agree not to
+publicly disclose any details of the security issue until the embargo date
+expires.
+
+The general aim of the team is to have embargo dates which are two weeks or less
+in duration. If a problem is identified with a proposed patch for a security
+issue, requiring further investigation and bug fixing, the embargo clock may be
+restarted. In exceptional circumstances longer initial embargoes may be
+negotiated by mutual agreement between members of the security team and other
+relevant parties to the problem. Any such extended embargoes will aim to be at
+most one month in duration.
+
+CVE allocation
+--------------
+
+The libvirt security team will associate each security issue with a CVE number.
+The CVE numbers will usually be allocated by one of the vendor security
+engineers on the security team.
+
+Branch fixing policy
+--------------------
+
+The security team will publish fixes for GIT master (which will become the next
+major release). The distro maintainers will be responsible for backporting the
+officially published fixes to other release branches where applicable.

docs/strategy.html.in

@@ -1,133 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Project Strategy</h1>
-
-    <p>
-      This document attempts to outline the libvirt project strategy for
-      the near future. Think of this as a high level vision or to-do list
-      setting the direction for the project and its developers to take.
-    </p>
-
-    <h2>Language consolidation</h2>
-
-    <p>
-      At time of writing libvirt uses the following languages:
-    </p>
-
-    <dl>
-      <dt>C</dt>
-      <dd>The core libvirt library, daemons, and helper tools are all written
-        in the C language.</dd>
-      <dt>Python</dt>
-      <dd>Various supporting build/test scripts are written in Python, with
-        compatibility for Python 3.</dd>
-      <dt>Perl</dt>
-      <dd>Various supporting build/test scripts are written in Perl. It is
-        also used for many syntax-check inline rules</dd>
-      <dt>Shell</dt>
-      <dd>Shell is used for some simple build/test scripts. At runtime
-        libvirt avoids shell except when using SSH tunnels to a remote
-        host</dd>
-      <dt>XSLT</dt>
-      <dd>The website uses XSLT for its templating system. The API
-        documentation is also autogenerated from an XML description
-        using XSLT</dd>
-      <dt>HTML</dt>
-      <dd>The website documentation is all written in plain HTML. Some HTML
-        is also auto-generated for API documentation</dd>
-      <dt>Meson</dt>
-      <dd>The core build system uses the new Meson build system</dd>
-      <dt>make</dt>
-      <dd>The syntax-check uses make recipes</dd>
-      <dt>awk/sed</dt>
-      <dd>A number of the syntax-check inline rules involve use of awk/sed
-        scripts</dd>
-      <dt>POD</dt>
-      <dd>The command line manual pages are typically written in Perl's POD
-        format, and converted to troff</dd>
-    </dl>
-
-    <p>
-      The wide range of languages used present a knowledge burden for
-      developers involved in libvirt, especially when there are multiple
-      languages all used in the same problem spaces. This is most notable
-      in the build system which uses a combination of Meson, shell, awk,
-      sed, Perl and Python, with debugging requiring
-      understanding of the interactions between many languages. The
-      popularity of Perl has declined, while Python has become
-      more popular. This directly influences the amount and quality of
-      contributions that can be expected for programs written in the
-      respective languages.
-    </p>
-    <p>
-      The C language has served libvirt well over the years, but its age shows
-      giving rise to limitations which negatively impact the project in terms
-      of code quality, reliability, and efficiency of development. Most notably
-      its lack of memory safety means that many code bugs become trivially
-      exploitable security flaws or denial of service. The lack of a high
-      level portable runtime results in a lot of effort being spent to
-      ensure cross platform portability. The modern languages Rust and Go
-      provide viable options for low level systems programming, in a way that
-      is not practical with other common languages such as Python and Java.
-      There is thus a desire to make use of either Rust or Go, or a combination
-      of both, to incrementally replace existing use of C, and also for
-      greenfield development.
-    </p>
-    <p>
-      With this in mind the libvirt project has set a vision for language
-      usage in the future:
-    </p>
-
-    <dl>
-      <dt>C</dt>
-      <dd>Large parts of the core libvirt library, daemons, and helper tools
-        will continue to make use in the C language. Integration of other
-        languages will be an incremental, targeted process where they can
-        bring the greatest benefit.</dd>
-      <dt>Rust / Go</dt>
-      <dd>Parts of the core libvirt library, daemons and helper tools are to
-        leverage Rust or Go or both to replace C.</dd>
-      <dt>Meson</dt>
-      <dd>The core build system is to be written in Meson.</dd>
-      <dt>Python</dt>
-      <dd>Various supporting build/test scripts are written in Python 3
-        compatible mode only.</dd>
-      <dt>reStructuredText</dt>
-      <dd>The website and command man pages are to be written in RST, using
-        Sphinx as the engine to convert to end user formats like HTML, troff,
-        etc</dd>
-    </dl>
-
-    <p>
-      Some notable points from the above. Whether the core library / daemons
-      will use Rust or Go internally is still to be decided based on more
-      detailed evaluation to identify the best fit. The need to link and embed
-      this functionality in other processes has complex interactions both at a
-      technical and non-technical level. For standalone helper tools, either
-      language is viable, but there are fewer concerns around interactions with
-      other in-process code from 3rd parties. Thus a different decision may be
-      made for daemons/libraries vs tools. Any rewrite proposed for existing
-      functionality will have to weigh up the benefits of the new code,
-      against the risk of introducing regressions with respect to the previous
-      code.
-    </p>
-
-    <p>
-      Using the RST format for documentation allows for the use of XSLT to be
-      eliminated from the build process. RST and the Sphinx toolkit are widely
-      used, as seen by the huge repository of content on
-      <a href="https://readthedocs.org/">Read The Docs</a>.
-      The ability to embed raw HTML in the RST docs will greatly facilitate its
-      adoption, avoiding the need for a big bang conversion of existing content.
-      Given the desire to eliminate Perl usage, replacing the use of POD
-      documentation for manual pages is an obvious followup task. RST is the
-      obvious choice to achieve alignment with the website, allowing the man
-      pages to be easily published online with other docs. It is further
-      anticipated that the current API docs generator which uses XSLT to
-      convert the XML API description would be converted to something which
-      generates RST using Python instead of XSLT.
-    </p>
-  </body>
-</html>

docs/strategy.rst

@@ -0,0 +1,105 @@
+================
+Project Strategy
+================
+
+This document attempts to outline the libvirt project strategy for the near
+future. Think of this as a high level vision or to-do list setting the direction
+for the project and its developers to take.
+
+Language consolidation
+----------------------
+
+At time of writing libvirt uses the following languages:
+
+C
+   The core libvirt library, daemons, and helper tools are all written in the C
+   language.
+Python
+   Various supporting build/test scripts are written in Python, with
+   compatibility for Python 3.
+Perl
+   Various supporting build/test scripts are written in Perl. It is also used
+   for many syntax-check inline rules
+Shell
+   Shell is used for some simple build/test scripts. At runtime libvirt avoids
+   shell except when using SSH tunnels to a remote host
+XSLT
+   The website uses XSLT for its templating system. The API documentation is
+   also autogenerated from an XML description using XSLT
+HTML
+   The website documentation is all written in plain HTML. Some HTML is also
+   auto-generated for API documentation
+Meson
+   The core build system uses the new Meson build system
+make
+   The syntax-check uses make recipes
+awk/sed
+   A number of the syntax-check inline rules involve use of awk/sed scripts
+POD
+   The command line manual pages are typically written in Perl's POD format, and
+   converted to troff
+
+The wide range of languages used present a knowledge burden for developers
+involved in libvirt, especially when there are multiple languages all used in
+the same problem spaces. This is most notable in the build system which uses a
+combination of Meson, shell, awk, sed, Perl and Python, with debugging requiring
+understanding of the interactions between many languages. The popularity of Perl
+has declined, while Python has become more popular. This directly influences the
+amount and quality of contributions that can be expected for programs written in
+the respective languages.
+
+The C language has served libvirt well over the years, but its age shows giving
+rise to limitations which negatively impact the project in terms of code
+quality, reliability, and efficiency of development. Most notably its lack of
+memory safety means that many code bugs become trivially exploitable security
+flaws or denial of service. The lack of a high level portable runtime results in
+a lot of effort being spent to ensure cross platform portability. The modern
+languages Rust and Go provide viable options for low level systems programming,
+in a way that is not practical with other common languages such as Python and
+Java. There is thus a desire to make use of either Rust or Go, or a combination
+of both, to incrementally replace existing use of C, and also for greenfield
+development.
+
+With this in mind the libvirt project has set a vision for language usage in the
+future:
+
+C
+   Large parts of the core libvirt library, daemons, and helper tools will
+   continue to make use in the C language. Integration of other languages will
+   be an incremental, targeted process where they can bring the greatest
+   benefit.
+Rust / Go
+   Parts of the core libvirt library, daemons and helper tools are to leverage
+   Rust or Go or both to replace C.
+Meson
+   The core build system is to be written in Meson.
+Python
+   Various supporting build/test scripts are written in Python 3 compatible mode
+   only.
+reStructuredText
+   The website and command man pages are to be written in RST, using Sphinx as
+   the engine to convert to end user formats like HTML, troff, etc
+
+Some notable points from the above. Whether the core library / daemons will use
+Rust or Go internally is still to be decided based on more detailed evaluation
+to identify the best fit. The need to link and embed this functionality in other
+processes has complex interactions both at a technical and non-technical level.
+For standalone helper tools, either language is viable, but there are fewer
+concerns around interactions with other in-process code from 3rd parties. Thus a
+different decision may be made for daemons/libraries vs tools. Any rewrite
+proposed for existing functionality will have to weigh up the benefits of the
+new code, against the risk of introducing regressions with respect to the
+previous code.
+
+Using the RST format for documentation allows for the use of XSLT to be
+eliminated from the build process. RST and the Sphinx toolkit are widely used,
+as seen by the huge repository of content on `Read The
+Docs <https://readthedocs.org/>`__. The ability to embed raw HTML in the RST
+docs will greatly facilitate its adoption, avoiding the need for a big bang
+conversion of existing content. Given the desire to eliminate Perl usage,
+replacing the use of POD documentation for manual pages is an obvious followup
+task. RST is the obvious choice to achieve alignment with the website, allowing
+the man pages to be easily published online with other docs. It is further
+anticipated that the current API docs generator which uses XSLT to convert the
+XML API description would be converted to something which generates RST using
+Python instead of XSLT.

docs/support.html.in

@@ -1,258 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Support guarantees</h1>
-
-    <ul id="toc"></ul>
-
-    <p>
-      This document will outline the support status / guarantees around the
-      very interfaces that libvirt exposes to applications and/or system
-      administrators. The intent is to help users understand what features they
-      can rely upon in particular scenarios, and whether they are likely to
-      suffer disruption during upgrades.
-    </p>
-
-    <h2><a id="publicAPI">Primary public API</a></h2>
-
-    <p>
-      The main public API provided by <code>libvirt.so</code> and described
-      in <code>libvirt/libvirt.h</code> exposes the primary hypervisor
-      agnostic management interface of libvirt. This API has the strongest
-      guarantee of any part of libvirt with a promise to keep backwards
-      compatibility forever. Specific details are as follows:
-    </p>
-
-    <dl>
-      <dt>Functions</dt>
-      <dd>Functions will never be removed from the public API, and will
-        never have parameters added, removed or changed in their signature.
-        IOW they will be ABI compatible forever. The semantics implied by
-        a specific set of parameters passed to the function will remain
-        unchanged. Where a parameter accepts a bitset of feature flags, or
-        an enumerated value, further flags / enum values may be supported
-        in the future. Where a parameter accepts one of a set of related
-        constants, further constants may be supported in the future.
-      </dd>
-      <dt>Struct types</dt>
-      <dd>Once defined in a release, struct definitions will never have any
-        fields add, removed or changed in any way. Their size and layout is
-        fixed forever. If a struct name starts with an underscore, it is
-        considered acceptable to rename it. Applications should thus always
-        use the corresponding typedef in preference to the struct name.
-      </dd>
-      <dt>Union types</dt>
-      <dd>Once defined in a release, union definitions will never have any
-        existing fields removed or changed. New union choices may be added,
-        provided that they don't change the size of the existing union
-        definition. If a struct name starts with an underscore, it is
-        considered acceptable to rename it. Applications should thus always
-        use the corresponding typedef in preference to the struct name.
-      </dd>
-      <dt>Type definitions</dt>
-      <dd>Most custom data types used in the APIs have corresponding typedefs
-        provided for their stable names. The typedefs should always be used
-        in preference to the underlying data type name, as the latter are not
-        guaranteed to be stable.
-      </dd>
-      <dt>Enumerations</dt>
-      <dd>Once defined in a release, existing enumeration values will never
-        be removed or renamed. New enumeration values may be introduced at
-        any time. Every enumeration will have a '_LAST' value which indicates
-        the current highest enumeration value, which may increase with new
-        releases. If an enumeration name starts with an underscore, it is
-        considered acceptable to rename it. Applications should thus always
-        use the corresponding typedef in preference to the enum name.
-      </dd>
-      <dt>Constants</dt>
-      <dd>Once defined in a release, existing constants will never be removed
-        or have their value changed. Most constants are grouped into related
-        sets, and within each set, new constants may be introduced. APIs which
-        use the constants may thus accept or return new constant values over
-        time.
-      </dd>
-      <dt>Symbol versions</dt>
-      <dd>Where the platform library format permits, APIs defined in libvirt.so
-        library will have version information associated. Each API will be
-        tagged with the version in which it was introduced, and this won't
-        be changed thereafter.
-      </dd>
-    </dl>
-
-    <h2><a id="hvAPI">Hypervisor specific APIs</a></h2>
-
-    <p>
-      A number of hypervisor drivers provide additional libraries with hypervisor
-      specific APIs, extending the core libvirt API. These add-on libraries follow
-      the same general principles described above, however, they are <strong>not</strong>
-      guaranteed to be preserved forever. The project reserves the right to remove
-      hypervisor specific APIs in any new release, or to change their semantics.
-      That said the project will endeavour to maintain API compatibility for as long
-      as is practical.
-    </p>
-
-    <p>
-      Use of some hypervisor specific APIs may result in the running guest being
-      marked as "tainted" if the API is at risk of having unexpected interactions
-      with normal libvirt operations. An application which chooses to make use of
-      hypervisor specific APIs should validate their operation with each new release
-      of libvirt and each new release of the underlying hypervisor. The semantics
-      may change in unexpected ways, or have unforeseen interactions with libvirt's
-      operation.
-    </p>
-
-    <h2><a id="apierrors">Error reporting</a></h2>
-
-    <p>
-      Most API calls are subject to failure and so will report error codes and
-      messages. Libvirt defines error codes for a wide variety of scenarios, some
-      represent very specific problems, while others are general purpose for
-      broad classes of problem. Over time the error codes reported are liable
-      to change, usually changing from a generic error to a more specific error.
-      Thus applications should be careful about checking for &amp; taking action
-      upon specific error codes, as their behaviour may change across releases.
-    </p>
-
-    <h2><a id="xmlschema">XML schemas</a></h2>
-
-    <p>
-      The main objects exposed via the primary libvirt public API are usually
-      configured via XML documents following specific schemas. The XML schemas
-      are considered to be stable formats, whose compatibility will be maintained
-      forever. Specific details are as follows:
-    </p>
-
-    <dl>
-      <dt>Attributes</dt>
-      <dd>Attributes defined on an XML element will never be removed or
-        renamed. New attributes may be defined. If the set of valid values
-        for an attribute are determined by an enumeration, the permitted
-        values will never be removed or renamed, only new values defined.
-        None the less, specific hypervisors may reject usage of certain
-        values according to their feature set.
-      </dd>
-      <dt>Elements</dt>
-      <dd>Elements defined will never be removed or renamed. New child
-        elements may be defined at any time. In places where only a
-        single instance of a named XML element is used, future versions
-        may be extended to permit multiple instances of the named XML
-        element to be used. An element which currently has no content
-        may later gain child elements.
-      </dd>
-    </dl>
-
-    <p>
-      Some hypervisor drivers may choose to allow use of hypervisor specific
-      extensions to the XML documents. These extensions will always be
-      contained within a hypervisor specific XML namespace. There is generally
-      no guarantee of long term support for the hypervisor specific extensions
-      across releases, though the project will endeavour to preserve them as
-      long as is possible. Applications choosing to use hypervisor specific
-      extensions should validate their operation against new libvirt or
-      hypervisor releases.
-    </p>
-
-    <h2><a id="configfiles">Configuration files</a></h2>
-
-    <p>
-      A number of programs / daemons provided libvirt rely on host filesystem
-      configuration files. These configuration files are accompanied by augeas
-      lens for easy manipulation by applications. There is in general no
-      guarantee that parameters available in the configuration file will be
-      preserved across releases, though the project will endeavour to preserve
-      them as long as is possible. If a configuration option is dropped from
-      the file, the augeas lens will retain the ability to read that configuration
-      parameter, so that it is able to read &amp; update historically modified
-      files.
-
-      The default configuration files ship with all parameters commented out
-      such that a deployment relies on the built-in defaults of the application
-      in question. There is no guarantee that the defaults will remain the same
-      across releases. A deployment that expects a particular value for a
-      configuration parameter should consider defining it explicitly, instead
-      of relying on the defaults.
-    </p>
-
-    <h2><a id="hvdrivers">Hypervisor drivers</a></h2>
-
-    <p>
-      The libvirt project provides support for a wide variety of hypervisor
-      drivers. These drivers target certain versions of the hypervisor's
-      underlying management APIs. In general libvirt aims to work with any
-      hypervisor version that is still broadly supported by its vendor.
-      When a vendor discontinues support for a particular hypervisor
-      version it will be dropped by libvirt. Libvirt may choose to drop
-      support for a particular hypervisor version prior to the vendor
-      ending support, if it deems that the likely usage is too small to
-      justify the ongoing maintenance cost.
-    </p>
-    <p>
-      Each hypervisor release will implement a distinct subset of features
-      that can be expressed in the libvirt APIs and XML formats. While the
-      XML schema syntax will be stable across releases, libvirt is unable
-      to promise that it will always be able to support usage of the same
-      features across hypervisor releases. Where a hypervisor changes the
-      way a feature is implemented, the project will endeavour to adapt
-      to the new implementation to provide the same semantics. In cases
-      where the feature is discontinued by the hypervisor, libvirt will
-      return an error indicating it is not supported. Likewise libvirt will
-      make reasonable efforts to keep API calls working across hypervisor
-      releases even if the underlying implementation changes. In cases where
-      this is impossible, a suitable error will be reported. The list of
-      APIs which have implementations <a href="hvsupport.html">is detailed separately</a>.
-    </p>
-
-    <h2><a id="rpcproto">RPC protocol</a></h2>
-
-    <p>
-      For some hypervisor drivers, the libvirt.so library communicates with
-      separate libvirt daemons to perform work. This communication takes
-      place over a binary RPC protocol defined by libvirt. The protocol uses
-      the XDR format for data encoding, and the message packet format is
-      defined in libvirt source code.
-    </p>
-    <p>
-      Applications are encouraged to use the primary libvirt.so library which
-      transparently talks to the daemons, so that they are not exposed to the
-      hypervisor driver specific details. None the less, the RPC protocol
-      associated with the libvirtd is considered to be a long term stable ABI.
-      It will only ever have new messages added to it, existing messages will
-      not be removed, nor have their contents changed. Thus if an application
-      does wish to provide its own client side implementation of the RPC
-      protocol this is supported, with the caveat that the application will
-      loose the ability to work with certain hypervisors libvirt supports.
-      The project reserves the right to define new authentication and encryption
-      options for the protocol, and the defaults used in this area may change
-      over time. This is particularly true of the TLS ciphers permitted. Thus
-      applications choosing to implement the RPC protocol must be prepared to
-      track support for new security options. If defaults are changed, however,
-      it will generally be possible to reconfigure the daemon to use the old
-      defaults, albeit with possible implications for system security.
-    </p>
-
-    <p>
-      Other daemons besides, libvirtd, also use the same RPC protocol, but
-      with different message types defined. These RPC protocols are all
-      considered to be private implementations that are liable to change
-      at any time. Applications must not attempt to talk to these other
-      daemons directly.
-    </p>
-
-    <h2><a id="virsh">virsh client</a></h2>
-
-    <p>
-      The virsh program provides a simple client to interact with an arbitrary libvirt
-      hypervisor connection. Since it uses the primary public API of libvirt, it should
-      generally inherit the guarantees associated with that API, and with the hypervisor
-      driver. The commands that virsh exposes, and the arguments they accept are all
-      considered to be long term stable. Existing commands and arguments will not be
-      removed or renamed. New commands and arguments may be added in new releases.
-      The text output format produced by virsh commands is not generally guaranteed to
-      be stable if it contains compound data (eg formatted tables or lists). Commands
-      which output single data items (ie an object name, or an XML document), can be
-      treated as having stable format.
-    </p>
-
-  </body>
-</html>

docs/support.rst

@@ -0,0 +1,207 @@
+==================
+Support guarantees
+==================
+
+.. contents::
+
+This document will outline the support status / guarantees around the very
+interfaces that libvirt exposes to applications and/or system administrators.
+The intent is to help users understand what features they can rely upon in
+particular scenarios, and whether they are likely to suffer disruption during
+upgrades.
+
+Primary public API
+------------------
+
+The main public API provided by ``libvirt.so`` and described in
+``libvirt/libvirt.h`` exposes the primary hypervisor agnostic management
+interface of libvirt. This API has the strongest guarantee of any part of
+libvirt with a promise to keep backwards compatibility forever. Specific details
+are as follows:
+
+Functions
+   Functions will never be removed from the public API, and will never have
+   parameters added, removed or changed in their signature. IOW they will be ABI
+   compatible forever. The semantics implied by a specific set of parameters
+   passed to the function will remain unchanged. Where a parameter accepts a
+   bitset of feature flags, or an enumerated value, further flags / enum values
+   may be supported in the future. Where a parameter accepts one of a set of
+   related constants, further constants may be supported in the future.
+Struct types
+   Once defined in a release, struct definitions will never have any fields add,
+   removed or changed in any way. Their size and layout is fixed forever. If a
+   struct name starts with an underscore, it is considered acceptable to rename
+   it. Applications should thus always use the corresponding typedef in
+   preference to the struct name.
+Union types
+   Once defined in a release, union definitions will never have any existing
+   fields removed or changed. New union choices may be added, provided that they
+   don't change the size of the existing union definition. If a struct name
+   starts with an underscore, it is considered acceptable to rename it.
+   Applications should thus always use the corresponding typedef in preference
+   to the struct name.
+Type definitions
+   Most custom data types used in the APIs have corresponding typedefs provided
+   for their stable names. The typedefs should always be used in preference to
+   the underlying data type name, as the latter are not guaranteed to be stable.
+Enumerations
+   Once defined in a release, existing enumeration values will never be removed
+   or renamed. New enumeration values may be introduced at any time. Every
+   enumeration will have a '_LAST' value which indicates the current highest
+   enumeration value, which may increase with new releases. If an enumeration
+   name starts with an underscore, it is considered acceptable to rename it.
+   Applications should thus always use the corresponding typedef in preference
+   to the enum name.
+Constants
+   Once defined in a release, existing constants will never be removed or have
+   their value changed. Most constants are grouped into related sets, and within
+   each set, new constants may be introduced. APIs which use the constants may
+   thus accept or return new constant values over time.
+Symbol versions
+   Where the platform library format permits, APIs defined in libvirt.so library
+   will have version information associated. Each API will be tagged with the
+   version in which it was introduced, and this won't be changed thereafter.
+
+Hypervisor specific APIs
+------------------------
+
+A number of hypervisor drivers provide additional libraries with hypervisor
+specific APIs, extending the core libvirt API. These add-on libraries follow the
+same general principles described above, however, they are **not** guaranteed to
+be preserved forever. The project reserves the right to remove hypervisor
+specific APIs in any new release, or to change their semantics. That said the
+project will endeavour to maintain API compatibility for as long as is
+practical.
+
+Use of some hypervisor specific APIs may result in the running guest being
+marked as "tainted" if the API is at risk of having unexpected interactions with
+normal libvirt operations. An application which chooses to make use of
+hypervisor specific APIs should validate their operation with each new release
+of libvirt and each new release of the underlying hypervisor. The semantics may
+change in unexpected ways, or have unforeseen interactions with libvirt's
+operation.
+
+Error reporting
+---------------
+
+Most API calls are subject to failure and so will report error codes and
+messages. Libvirt defines error codes for a wide variety of scenarios, some
+represent very specific problems, while others are general purpose for broad
+classes of problem. Over time the error codes reported are liable to change,
+usually changing from a generic error to a more specific error. Thus
+applications should be careful about checking for & taking action upon specific
+error codes, as their behaviour may change across releases.
+
+XML schemas
+-----------
+
+The main objects exposed via the primary libvirt public API are usually
+configured via XML documents following specific schemas. The XML schemas are
+considered to be stable formats, whose compatibility will be maintained forever.
+Specific details are as follows:
+
+Attributes
+   Attributes defined on an XML element will never be removed or renamed. New
+   attributes may be defined. If the set of valid values for an attribute are
+   determined by an enumeration, the permitted values will never be removed or
+   renamed, only new values defined. None the less, specific hypervisors may
+   reject usage of certain values according to their feature set.
+Elements
+   Elements defined will never be removed or renamed. New child elements may be
+   defined at any time. In places where only a single instance of a named XML
+   element is used, future versions may be extended to permit multiple instances
+   of the named XML element to be used. An element which currently has no
+   content may later gain child elements.
+
+Some hypervisor drivers may choose to allow use of hypervisor specific
+extensions to the XML documents. These extensions will always be contained
+within a hypervisor specific XML namespace. There is generally no guarantee of
+long term support for the hypervisor specific extensions across releases, though
+the project will endeavour to preserve them as long as is possible. Applications
+choosing to use hypervisor specific extensions should validate their operation
+against new libvirt or hypervisor releases.
+
+Configuration files
+-------------------
+
+A number of programs / daemons provided libvirt rely on host filesystem
+configuration files. These configuration files are accompanied by augeas lens
+for easy manipulation by applications. There is in general no guarantee that
+parameters available in the configuration file will be preserved across
+releases, though the project will endeavour to preserve them as long as is
+possible. If a configuration option is dropped from the file, the augeas lens
+will retain the ability to read that configuration parameter, so that it is able
+to read & update historically modified files. The default configuration files
+ship with all parameters commented out such that a deployment relies on the
+built-in defaults of the application in question. There is no guarantee that the
+defaults will remain the same across releases. A deployment that expects a
+particular value for a configuration parameter should consider defining it
+explicitly, instead of relying on the defaults.
+
+Hypervisor drivers
+------------------
+
+The libvirt project provides support for a wide variety of hypervisor drivers.
+These drivers target certain versions of the hypervisor's underlying management
+APIs. In general libvirt aims to work with any hypervisor version that is still
+broadly supported by its vendor. When a vendor discontinues support for a
+particular hypervisor version it will be dropped by libvirt. Libvirt may choose
+to drop support for a particular hypervisor version prior to the vendor ending
+support, if it deems that the likely usage is too small to justify the ongoing
+maintenance cost.
+
+Each hypervisor release will implement a distinct subset of features that can be
+expressed in the libvirt APIs and XML formats. While the XML schema syntax will
+be stable across releases, libvirt is unable to promise that it will always be
+able to support usage of the same features across hypervisor releases. Where a
+hypervisor changes the way a feature is implemented, the project will endeavour
+to adapt to the new implementation to provide the same semantics. In cases where
+the feature is discontinued by the hypervisor, libvirt will return an error
+indicating it is not supported. Likewise libvirt will make reasonable efforts to
+keep API calls working across hypervisor releases even if the underlying
+implementation changes. In cases where this is impossible, a suitable error will
+be reported. The list of APIs which have implementations `is detailed
+separately <hvsupport.html>`__.
+
+RPC protocol
+------------
+
+For some hypervisor drivers, the libvirt.so library communicates with separate
+libvirt daemons to perform work. This communication takes place over a binary
+RPC protocol defined by libvirt. The protocol uses the XDR format for data
+encoding, and the message packet format is defined in libvirt source code.
+
+Applications are encouraged to use the primary libvirt.so library which
+transparently talks to the daemons, so that they are not exposed to the
+hypervisor driver specific details. None the less, the RPC protocol associated
+with the libvirtd is considered to be a long term stable ABI. It will only ever
+have new messages added to it, existing messages will not be removed, nor have
+their contents changed. Thus if an application does wish to provide its own
+client side implementation of the RPC protocol this is supported, with the
+caveat that the application will loose the ability to work with certain
+hypervisors libvirt supports. The project reserves the right to define new
+authentication and encryption options for the protocol, and the defaults used in
+this area may change over time. This is particularly true of the TLS ciphers
+permitted. Thus applications choosing to implement the RPC protocol must be
+prepared to track support for new security options. If defaults are changed,
+however, it will generally be possible to reconfigure the daemon to use the old
+defaults, albeit with possible implications for system security.
+
+Other daemons besides, libvirtd, also use the same RPC protocol, but with
+different message types defined. These RPC protocols are all considered to be
+private implementations that are liable to change at any time. Applications must
+not attempt to talk to these other daemons directly.
+
+virsh client
+------------
+
+The virsh program provides a simple client to interact with an arbitrary libvirt
+hypervisor connection. Since it uses the primary public API of libvirt, it
+should generally inherit the guarantees associated with that API, and with the
+hypervisor driver. The commands that virsh exposes, and the arguments they
+accept are all considered to be long term stable. Existing commands and
+arguments will not be removed or renamed. New commands and arguments may be
+added in new releases. The text output format produced by virsh commands is not
+generally guaranteed to be stable if it contains compound data (eg formatted
+tables or lists). Commands which output single data items (ie an object name, or
+an XML document), can be treated as having stable format.

docs/testapi.html.in

@@ -1,35 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>libvirt-test-API:  Python based test suite </h1>
-    <p>Libvirt-test-API is a powerful test tool designed to complement
-       existing libvirt test tools such as libvirt-TCK and the internal
-       test suite. It aims at functional regression testing, trying to
-       exercise nearly all the API by the way of the Python bindings.</p>
-    <p>The test API currently covers:</p>
-    <ul>
-      <li>domain: all classical lifetime operations, installation of
-          various guests OSes, snapshots</li>
-      <li>interfaces: define, create, destroy, undefine, NPIV</li>
-      <li>virtual networks: define, create, destroy, undefine</li>
-      <li>storage: regression tests for most storage types and configurations
-          dir, disk, netfs, iSCSI, multipath</li>
-    </ul>
-    <p>Some of the tests need dedicated local resources whose definitions
-       are stored in a configuration file. The tests are defined using
-       Python modules defining the code for the test, this is called
-       a <tt>test case</tt>, and test <tt>configuration files</tt> using one
-       or more test case to define a given test scenario.</p>
-    <p>For more details you can look at:</p>
-    <ul>
-      <li> A <a href="https://libvirt.org/sources/libvirt-test-API/Libvirt-test-API.pdf">documentation PDF</a>
-           file describing the test suite and how to write test cases
-           and test scenarios.</li>
-    </ul>
-    <p> Libvirt-test-API is maintained using
-        <a href="https://gitlab.com/libvirt/libvirt-test-API">a GIT
-        repository</a>, and comment, patches and reviews are carried
-        on the <a href="contact.html">libvir-list</a> development list.</p>
-  </body>
-</html>

docs/testapi.rst

@@ -0,0 +1,34 @@
+=========================================
+libvirt-test-API: Python based test suite
+=========================================
+
+Libvirt-test-API is a powerful test tool designed to complement existing libvirt
+test tools such as libvirt-TCK and the internal test suite. It aims at
+functional regression testing, trying to exercise nearly all the API by the way
+of the Python bindings.
+
+The test API currently covers:
+
+-  domain: all classical lifetime operations, installation of various guests
+   OSes, snapshots
+-  interfaces: define, create, destroy, undefine, NPIV
+-  virtual networks: define, create, destroy, undefine
+-  storage: regression tests for most storage types and configurations dir,
+   disk, netfs, iSCSI, multipath
+
+Some of the tests need dedicated local resources whose definitions are stored in
+a configuration file. The tests are defined using Python modules defining the
+code for the test, this is called a test case, and test configuration files
+using one or more test case to define a given test scenario.
+
+For more details you can look at:
+
+-  A `documentation
+   PDF <https://libvirt.org/sources/libvirt-test-API/Libvirt-test-API.pdf>`__
+   file describing the test suite and how to write test cases and test
+   scenarios.
+
+Libvirt-test-API is maintained using `a GIT
+repository <https://gitlab.com/libvirt/libvirt-test-API>`__, and comment,
+patches and reviews are carried on the `libvir-list <contact.html>`__
+development list.

docs/testsuites.html.in

@@ -1,41 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Test suites</h1>
-    <p>There is a few test suites available to developers for testing
-    a given version of libvirt:</p>
-    <ul>
-      <li>the internal test suite: present in the source code, it is run
-          by developers before submitting patches upstream, it is also
-          suggested to have it run and pass as part of the packaging
-          process for distributions. It is run by launching:
-          <pre>make check (libvirt 6.6.0 and older)</pre>
-          <pre>ninja test (libvirt 6.7.0 and newer)</pre>
-          in a source tree after compilation has finished. It doesn't
-          really make functional testing but checks that large portions
-          of the code not interacting directly with virtualization
-          functions properly.
-      </li>
-      <li>the <a href="testtck.html">TCK test suite</a> is a functional
-          test suite implemented using the
-          <a href="https://search.cpan.org/dist/Sys-Virt/">Perl bindings</a>
-          of libvirt. It is available separately as a
-          <a href="ftp://libvirt.org/libvirt/tck/">download</a>, as a
-          <a href="https://rpmfind.net/linux/rpm2html/search.php?query=libvirt-tck">package</a>
-          in Fedora distributions, but best is probably to get
-          the <a href="https://gitlab.com/libvirt/libvirt-tck">version
-          from GIT</a>.
-      </li>
-      <li>the <a href="testapi.html">libvirt-test-API</a> is also a functional
-          test suite, but implemented using the
-          <a href="python.html">Python bindings</a>
-          of libvirt. It is available separately as a
-          <a href="ftp://libvirt.org/libvirt/libvirt-test-API/">download</a>,
-          or directly get
-          the <a href="https://gitlab.com/libvirt/libvirt-test-API/">version
-          from GIT</a>.
-      </li>
-    </ul>
-  </body>
-</html>

docs/testsuites.rst

@@ -0,0 +1,37 @@
+===========
+Test suites
+===========
+
+There is a few test suites available to developers for testing a given version
+of libvirt:
+
+-  the internal test suite: present in the source code, it is run by developers
+   before submitting patches upstream, it is also suggested to have it run and
+   pass as part of the packaging process for distributions. It is run by
+   launching:
+
+   ::
+
+      make check (libvirt 6.6.0 and older)
+
+   ::
+
+      ninja test (libvirt 6.7.0 and newer)
+
+   in a source tree after compilation has finished. It doesn't really make
+   functional testing but checks that large portions of the code not interacting
+   directly with virtualization functions properly.
+
+-  the `TCK test suite <testtck.html>`__ is a functional test suite implemented
+   using the `Perl bindings <https://search.cpan.org/dist/Sys-Virt/>`__ of
+   libvirt. It is available separately as a
+   `download <ftp://libvirt.org/libvirt/tck/>`__, as a
+   `package <https://rpmfind.net/linux/rpm2html/search.php?query=libvirt-tck>`__
+   in Fedora distributions, but best is probably to get the `version from
+   GIT <https://gitlab.com/libvirt/libvirt-tck>`__.
+
+-  the `libvirt-test-API <testapi.html>`__ is also a functional test suite, but
+   implemented using the `Python bindings <python.html>`__ of libvirt. It is
+   available separately as a
+   `download <ftp://libvirt.org/libvirt/libvirt-test-API/>`__, or directly get
+   the `version from GIT <https://gitlab.com/libvirt/libvirt-test-API/>`__.

docs/testtck.html.in

@@ -1,40 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>libvirt TCK  : Technology Compatibility Kit</h1>
-    <p>The libvirt TCK provides a framework for performing testing
-    of the integration between libvirt drivers, the underlying virt
-    hypervisor technology, related operating system services and system
-    configuration. The idea (and name) is motivated by the Java TCK.</p>
-    <p>In particular the libvirt TCK is intended to address the following
-    scenarios:</p>
-    <ul>
-      <li>Validate that a new libvirt driver is in compliance
-          with the (possibly undocumented!) driver API semantics</li>
-      <li>Validate that an update to an existing driver does not
-         change the API semantics in a non-compliant manner</li>
-      <li>Validate that a new hypervisor release is still providing
-         compatibility with the corresponding libvirt driver usage</li>
-      <li>Validate that an OS distro deployment consisting of a
-         hypervisor and libvirt release is configured correctly</li>
-    </ul>
-    <p>Thus the libvirt TCK will allow developers, administrators and users
-    to determine the level of compatibility of their platform, and
-    evaluate whether it will meet their needs, and get awareness of any
-    regressions that may have occurred since a previous test run.</p>
-    <p>For more details you can look at:</p>
-    <ul>
-      <li> The initial
-<a href="https://www.redhat.com/archives/libvir-list/2009-April/msg00176.html">mail
-           from Daniel Berrange</a> presenting the project.</li>
-      <li> The <a href="https://fedoraproject.org/wiki/Features/VirtTCK">page
-           describing VirtTCK</a> the inclusion of libvirt-TCK as a
-           Fedora Feature.</li>
-    </ul>
-    <p> Libvirt-TCK is maintained using
-        <a href="https://gitlab.com/libvirt/libvirt-tck">a GIT
-        repository</a>, and comment, patches and reviews are carried
-        on the <a href="contact.html">libvir-list</a> development list.</p>
-  </body>
-</html>

docs/testtck.rst

@@ -0,0 +1,37 @@
+==========================================
+libvirt TCK : Technology Compatibility Kit
+==========================================
+
+The libvirt TCK provides a framework for performing testing of the integration
+between libvirt drivers, the underlying virt hypervisor technology, related
+operating system services and system configuration. The idea (and name) is
+motivated by the Java TCK.
+
+In particular the libvirt TCK is intended to address the following scenarios:
+
+-  Validate that a new libvirt driver is in compliance with the (possibly
+   undocumented!) driver API semantics
+-  Validate that an update to an existing driver does not change the API
+   semantics in a non-compliant manner
+-  Validate that a new hypervisor release is still providing compatibility with
+   the corresponding libvirt driver usage
+-  Validate that an OS distro deployment consisting of a hypervisor and libvirt
+   release is configured correctly
+
+Thus the libvirt TCK will allow developers, administrators and users to
+determine the level of compatibility of their platform, and evaluate whether it
+will meet their needs, and get awareness of any regressions that may have
+occurred since a previous test run.
+
+For more details you can look at:
+
+-  The initial `mail from Daniel
+   Berrange <https://www.redhat.com/archives/libvir-list/2009-April/msg00176.html>`__
+   presenting the project.
+-  The `page describing
+   VirtTCK <https://fedoraproject.org/wiki/Features/VirtTCK>`__ the inclusion of
+   libvirt-TCK as a Fedora Feature.
+
+Libvirt-TCK is maintained using `a GIT
+repository <https://gitlab.com/libvirt/libvirt-tck>`__, and comment, patches and
+reviews are carried on the `libvir-list <contact.html>`__ development list.

docs/virshcmdref.html.in

@@ -1,75 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <body>
-    <h1>Virsh Command Reference</h1>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="description">Description</a></h2>
-
-    <p>
-      The new <b>Virsh Command Reference</b>, for documenting the commands
-      in virsh, has recently been started.  Only covering the Virtual
-      Networking commands initially, it will expand to cover all virsh
-      commands over time.
-    </p>
-
-    <p>
-      If you would like to assist, content contributions are gladly accepted.
-      Please email <a href="mailto:jclift@redhat.com">Justin Clift</a>
-      directly, or get in contact through any of the
-      <a href="contact.html">official libvirt mailing lists</a>.
-    </p>
-
-   <h2><a id="viewing">Viewing Online</a></h2>
-
-    <p>
-      The latest version can be viewed directly online:
-    </p>
-
-    <ul>
-      <li>
-        <a href="https://libvirt.org/sources/virshcmdref/html/">Standard HTML format, multiple pages</a>
-      </li>
-      <li>
-        <a href="https://libvirt.org/sources/virshcmdref/html-single/">HTML format, one long page</a>
-      </li>
-    </ul>
-
-    <h2><a id="downloading">Downloading</a></h2>
-
-    <p>
-      The latest version of the Virsh Command Reference can be downloaded:
-    </p>
-
-    <ul>
-      <li>
-        Standard HTML format, multiple pages
-        (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-multi-page.tar.gz">.tar.gz</a>)
-        (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-multi-page.tar.bz2">.tar.bz2</a>)
-        (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-multi-page.zip">.zip</a>)
-      </li>
-      <li>
-        HTML format, one long page
-        (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-single.tar.gz">.tar.gz</a>)
-        (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-single.tar.bz2">.tar.bz2</a>)
-        (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-single.zip">.zip</a>)
-      </li>
-      <li>
-        <a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1.pdf">PDF format</a>
-      </li>
-      <li>
-        <a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1.epub">ePub format</a>
-      </li>
-    </ul>
-
-    <h2><a id="git">DocBook source GIT repository</a></h2>
-    <p>
-      The DocBook source is archived in a <a
-      href="https://git-scm.com/">git</a> repository available on
-      <a href="https://gitlab.com/libvirt/libvirt-virshcmdref">gitlab.com</a>.
-    </p>
-
-  </body>
-</html>

examples/c/misc/event-test.c

@@ -12,18 +12,8 @@
 #define G_N_ELEMENTS(Array) (sizeof(Array) / sizeof(*(Array)))
 #define STREQ(a, b) (strcmp(a, b) == 0)
 #define NULLSTR(s) ((s) ? (s) : "<null>")
-
+#define G_STATIC_ASSERT(cond) _Static_assert(cond, "verify (" #cond ")")
-#if (4 < __GNUC__ + (6 <= __GNUC_MINOR__) \
+#define G_GNUC_UNUSED __attribute__((__unused__))
-     && (201112L <= __STDC_VERSION__  || !defined __STRICT_ANSI__) \
-     && !defined __cplusplus)
-# define G_STATIC_ASSERT(cond) _Static_assert(cond, "verify (" #cond ")")
-#else
-# define G_STATIC_ASSERT(cond)
-#endif
-
-#ifndef G_GNUC_UNUSED
-# define G_GNUC_UNUSED __attribute__((__unused__))
-#endif
 
 int run = 1;
 

include/libvirt/libvirt-domain-snapshot.h

@@ -198,6 +198,7 @@ typedef enum {
     VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING = 1 << 0, /* Run after revert */
     VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED  = 1 << 1, /* Pause after revert */
     VIR_DOMAIN_SNAPSHOT_REVERT_FORCE   = 1 << 2, /* Allow risky reverts */
+    VIR_DOMAIN_SNAPSHOT_REVERT_RESET_NVRAM = 1 << 3, /* Re-initialize NVRAM from template */
 } virDomainSnapshotRevertFlags;
 
 /* Revert the domain to a point-in-time snapshot.  The

include/libvirt/libvirt-domain.h

@@ -62,7 +62,7 @@ typedef enum {
 # ifdef VIR_ENUM_SENTINELS
     VIR_DOMAIN_LAST
     /*
-     * NB: this enum value will increase over time as new events are
+     * NB: this enum value will increase over time as new states are
      * added to the libvirt API. It reflects the last state supported
      * by this version of the libvirt API.
      */
@@ -302,6 +302,7 @@ typedef enum {
     VIR_DOMAIN_START_BYPASS_CACHE = 1 << 2, /* Avoid file system cache pollution */
     VIR_DOMAIN_START_FORCE_BOOT   = 1 << 3, /* Boot, discarding any managed save */
     VIR_DOMAIN_START_VALIDATE     = 1 << 4, /* Validate the XML document against schema */
+    VIR_DOMAIN_START_RESET_NVRAM  = 1 << 5, /* Re-initialize NVRAM from template */
 } virDomainCreateFlags;
 
 
@@ -696,7 +697,7 @@ typedef enum {
     VIR_DOMAIN_CORE_DUMP_FORMAT_LAST
     /*
      * NB: this enum value will increase over time as new formats are
-     * added to the libvirt API. It reflects the last state supported
+     * added to the libvirt API. It reflects the last format supported
      * by this version of the libvirt API.
      */
 # endif
@@ -1268,6 +1269,7 @@ typedef enum {
     VIR_DOMAIN_SAVE_BYPASS_CACHE = 1 << 0, /* Avoid file system cache pollution */
     VIR_DOMAIN_SAVE_RUNNING      = 1 << 1, /* Favor running over paused */
     VIR_DOMAIN_SAVE_PAUSED       = 1 << 2, /* Favor paused over running */
+    VIR_DOMAIN_SAVE_RESET_NVRAM  = 1 << 3, /* Re-initialize NVRAM from template */
 } virDomainSaveRestoreFlags;
 
 int                     virDomainSave           (virDomainPtr domain,
@@ -2909,7 +2911,7 @@ typedef enum {
 # ifdef VIR_ENUM_SENTINELS
     VIR_KEYCODE_SET_LAST
     /*
-     * NB: this enum value will increase over time as new events are
+     * NB: this enum value will increase over time as new keycode sets are
      * added to the libvirt API. It reflects the last keycode set supported
      * by this version of the libvirt API.
      */
@@ -3281,7 +3283,7 @@ typedef enum {
  * @conn: virConnect connection
  * @dom: The domain on which the event occurred
  * @event: The specific virDomainEventType which occurred
- * @detail: event specific detail information
+ * @detail: event specific detail information (virDomainEvent*DetailType)
  * @opaque: opaque user data
  *
  * A callback function to be registered, and called when a domain event occurs
@@ -3783,7 +3785,7 @@ typedef enum {
  * virConnectDomainEventWatchdogCallback:
  * @conn: connection object
  * @dom: domain on which the event occurred
- * @action: action that is to be taken due to watchdog firing
+ * @action: action that is to be taken due to watchdog firing (virDomainEventWatchdogAction)
  * @opaque: application specified data
  *
  * The callback signature to use when registering for an event of type
@@ -3817,7 +3819,7 @@ typedef enum {
  * @dom: domain on which the event occurred
  * @srcPath: The host file on which the IO error occurred
  * @devAlias: The guest device alias associated with the path
- * @action: action that is to be taken due to the IO error
+ * @action: action that is to be taken due to the IO error (virDomainEventIOErrorAction)
  * @opaque: application specified data
  *
  * The callback signature to use when registering for an event of type
@@ -3836,7 +3838,7 @@ typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn,
  * @dom: domain on which the event occurred
  * @srcPath: The host file on which the IO error occurred
  * @devAlias: The guest device alias associated with the path
- * @action: action that is to be taken due to the IO error
+ * @action: action that is to be taken due to the IO error (virDomainEventIOErrorAction)
  * @reason: the cause of the IO error
  * @opaque: application specified data
  *
@@ -3940,7 +3942,7 @@ typedef virDomainEventGraphicsSubject *virDomainEventGraphicsSubjectPtr;
  * virConnectDomainEventGraphicsCallback:
  * @conn: connection object
  * @dom: domain on which the event occurred
- * @phase: the phase of the connection
+ * @phase: the phase of the connection (virDomainEventGraphicsPhase)
  * @local: the local server address
  * @remote: the remote client address
  * @authScheme: the authentication scheme activated
@@ -4054,7 +4056,7 @@ typedef void (*virConnectDomainEventDiskChangeCallback)(virConnectPtr conn,
                                                         void *opaque);
 
 /**
- * virConnectDomainEventTrayChangeReason:
+ * virDomainEventTrayChangeReason:
  *
  * The reason describing why the callback was called
  */
@@ -4072,7 +4074,7 @@ typedef enum {
  * @conn: connection object
  * @dom: domain on which the event occurred
  * @devAlias: device alias
- * @reason: why the tray status was changed?
+ * @reason: why the tray status was changed? (virDomainEventTrayChangeReason)
  * @opaque: application specified data
  *
  * This callback occurs when the tray of a removable device is moved.
@@ -4653,7 +4655,7 @@ typedef void (*virConnectDomainEventBlockThresholdCallback)(virConnectPtr conn,
  *             (virDomainMemoryFailureRecipientType)
  * @action: the action of hardware memory failure
  *          (virDomainMemoryFailureActionType)
- * @flags: the flags of hardware memory failure
+ * @flags: the flags of hardware memory failure (virDomainMemoryFailureFlags)
  * @opaque: application specified data
  *
  * The callback occurs when the hypervisor handles the hardware memory
@@ -5257,6 +5259,19 @@ typedef enum {
 # endif
 } virDomainDirtyRateStatus;
 
+/**
+ * virDomainDirtyRateCalcFlags:
+ *
+ * Flags OR'ed together to provide specific behaviour when calculating dirty page
+ * rate for a Domain
+ *
+ */
+typedef enum {
+    VIR_DOMAIN_DIRTYRATE_MODE_PAGE_SAMPLING = 0,        /* default mode - page-sampling */
+    VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_BITMAP = 1 << 0,    /* dirty-bitmap mode */
+    VIR_DOMAIN_DIRTYRATE_MODE_DIRTY_RING = 1 << 1,      /* dirty-ring mode */
+} virDomainDirtyRateCalcFlags;
+
 int virDomainStartDirtyRateCalc(virDomainPtr domain,
                                 int seconds,
                                 unsigned int flags);

include/libvirt/libvirt-network.h

@@ -262,7 +262,7 @@ typedef enum {
  * virConnectNetworkEventLifecycleCallback:
  * @conn: connection object
  * @net: network on which the event occurred
- * @event: The specific virNetworkEventLifeCycleType which occurred
+ * @event: The specific virNetworkEventLifecycleType which occurred
  * @detail: contains some details on the reason of the event.
  *          It will be 0 for the while.
  * @opaque: application specified data

include/libvirt/libvirt-nodedev.h

@@ -229,7 +229,7 @@ typedef enum {
  * virConnectNodeDeviceEventLifecycleCallback:
  * @conn: connection object
  * @dev: node device on which the event occurred
- * @event: The specific virNodeDeviceEventLifeCycleType which occurred
+ * @event: The specific virNodeDeviceEventLifecycleType which occurred
  * @detail: contains some details on the reason of the event.
  * @opaque: application specified data
  *