Browse Source

New upstream version 6.5.0

tags/upstream/6.5.0^0
Andrea Bolognani 7 months ago
parent
commit
38c0fa7429
100 changed files with 101928 additions and 44568 deletions
  1. +31
    -80
      ABOUT-NLS
  2. +21
    -12
      AUTHORS
  3. +12
    -11
      AUTHORS.in
  4. +2
    -2
      ChangeLog
  5. +1
    -22
      Makefile.am
  6. +50
    -38
      Makefile.in
  7. +0
    -2836
      NEWS
  8. +4156
    -0
      NEWS.rst
  9. +3
    -0
      README
  10. +3
    -0
      README.rst
  11. +10
    -1
      autogen.sh
  12. +1
    -1
      build-aux/syntax-check.mk
  13. +9
    -7
      ci/Makefile
  14. +6
    -18
      ci/list-images.sh
  15. +3
    -0
      config.h.in
  16. +57
    -10
      configure
  17. +1
    -1
      configure.ac
  18. +11
    -16
      docs/Makefile.am
  19. +23
    -19
      docs/Makefile.in
  20. +1
    -1
      docs/aclpolkit.html.in
  21. +3
    -3
      docs/apps.html.in
  22. +1
    -1
      docs/bindings.html.in
  23. +0
    -5
      docs/ci.rst
  24. +2
    -2
      docs/contribute.html.in
  25. +2
    -23
      docs/csharp.html.in
  26. +2
    -10
      docs/dbus.html.in
  27. +6
    -6
      docs/drvqemu.html.in
  28. +3
    -3
      docs/firewall.html.in
  29. +83
    -6
      docs/formatdomain.html.in
  30. +11
    -2
      docs/formatdomaincaps.html.in
  31. +14
    -0
      docs/formatnetwork.html.in
  32. +17
    -4
      docs/formatnode.html.in
  33. +7
    -7
      docs/hacking.rst
  34. +27
    -0
      docs/hooks.html.in
  35. +5
    -4
      docs/internals/rpc.html.in
  36. +2
    -10
      docs/java.html.in
  37. +9
    -0
      docs/kbase.html.in
  38. +1
    -1
      docs/kbase/backing_chains.rst
  39. +284
    -0
      docs/kbase/incrementalbackupinternals.rst
  40. +214
    -0
      docs/kbase/kvm-realtime.rst
  41. +6
    -3
      docs/kbase/launch_security_sev.rst
  42. +2
    -1
      docs/kbase/qemu-passthrough-security.rst
  43. +189
    -0
      docs/kbase/s390_protected_virt.rst
  44. +0
    -4
      docs/kbase/virtiofs.rst
  45. +0
    -15
      docs/libvirt.css
  46. +8
    -0
      docs/manpages/virsh.rst
  47. +1
    -1
      docs/migration.html.in
  48. +16
    -0
      docs/newreposetup.rst
  49. +0
    -28
      docs/news-2005.html.in
  50. +0
    -354
      docs/news-2006.html.in
  51. +0
    -534
      docs/news-2007.html.in
  52. +0
    -580
      docs/news-2008.html.in
  53. +0
    -1603
      docs/news-2009.html.in
  54. +0
    -2218
      docs/news-2010.html.in
  55. +0
    -3314
      docs/news-2011.html.in
  56. +0
    -3012
      docs/news-2012.html.in
  57. +0
    -3675
      docs/news-2013.html.in
  58. +0
    -3418
      docs/news-2014.html.in
  59. +0
    -2864
      docs/news-2015.html.in
  60. +0
    -3740
      docs/news-2016.html.in
  61. +0
    -69
      docs/news-ascii.xsl
  62. +0
    -106
      docs/news-html.xsl
  63. +0
    -72
      docs/news.rng
  64. +0
    -5418
      docs/news.xml
  65. +2
    -8
      docs/php.html.in
  66. +3
    -0
      docs/schemas/domaincaps.rng
  67. +97
    -59
      docs/schemas/domaincommon.rng
  68. +5
    -0
      docs/schemas/network.rng
  69. +13
    -5
      docs/schemas/nodedev.rng
  70. +1
    -1
      docs/securityprocess.html.in
  71. +1
    -1
      docs/testapi.html.in
  72. +2
    -2
      docs/testsuites.html.in
  73. +1
    -1
      docs/testtck.html.in
  74. +2
    -14
      docs/virshcmdref.html.in
  75. +1
    -0
      examples/Makefile.in
  76. +1
    -0
      include/libvirt/Makefile.in
  77. +6
    -3
      libvirt.spec
  78. +5
    -2
      libvirt.spec.in
  79. +3
    -0
      m4/virt-external-programs.m4
  80. +1
    -1
      mingw-libvirt.spec.in
  81. +42
    -0
      po/LINGUAS
  82. +14
    -53
      po/Makefile.am
  83. +15
    -53
      po/Makefile.in
  84. +1
    -0
      po/POTFILES.in
  85. +0
    -19
      po/af.mini.po
  86. +0
    -19
      po/am.mini.po
  87. +0
    -19
      po/anp.mini.po
  88. +0
    -23
      po/ar.mini.po
  89. +19119
    -694
      po/as.po
  90. +0
    -19
      po/ast.mini.po
  91. +0
    -19
      po/bal.mini.po
  92. +0
    -20
      po/be.mini.po
  93. +0
    -1133
      po/bg.mini.po
  94. +37955
    -0
      po/bg.po
  95. +0
    -21
      po/bn.mini.po
  96. +0
    -8131
      po/bn_IN.mini.po
  97. +39322
    -0
      po/bn_IN.po
  98. +0
    -19
      po/bo.mini.po
  99. +0
    -19
      po/br.mini.po
  100. +0
    -19
      po/brx.mini.po

+ 31
- 80
ABOUT-NLS View File

@@ -2,89 +2,40 @@
Libvirt Message Translation
===========================

Libvirt translatable messages are maintained using the GNU Gettext tools and
file formats, in combination with the Zanata web service.
.. image:: https://translate.fedoraproject.org/widgets/libvirt/-/libvirt/multi-auto.svg
:target: https://translate.fedoraproject.org/engage/libvirt/
:alt: Translation status

python-zanata-client is required in order to use make to pull/push translations
from/to Zanata server.
Libvirt translatable messages are maintained using the GNU Gettext tools and
file formats, in combination with the Fedora Weblate web service.

https://translate.fedoraproject.org/projects/libvirt/libvirt/

Source repository
=================

The libvirt GIT repository does NOT store the master "libvirt.pot" file, nor
does it store full "po" files for translations. The master "libvirt.pot" file
can be generated at any time using

::

$ make libvirt.pot

The translations are kept in minimized files that are the same file format
as normal po files but with all redundant information stripped and messages
re-ordered. The key differences between the ".mini.po" files in GIT and the
full ".po" files are

* msgids with no current translation are omitted
* msgids are sorted in alphabetical order not source file order
* msgids with a msgstr marked "fuzzy" are discarded
* source file locations are omitted

The full po files can be created at any time using

::

$ make update-po

This merges the "libvirt.pot" with the "$LANG.mini.po" for each language, to
create the "$LANG.po" files. These are included in the release archives created
by "make dist".

When a full po file is updated, changes can be propagated back into the
minimized po files using

::

$ make update-mini-po

Note, however, that this is generally not something that should be run by
developers normally, as it is triggered by 'make pull-po' when refreshing
content from Zanata.


Zanata web service
==================

The translation of libvirt messages has been outsourced to the Fedora
translation team using the Zanata web service:

https://fedora.zanata.org/project/view/libvirt

As such, changes to translations will generally NOT be accepted as patches
directly to libvirt GIT. Any changes made to "$LANG.mini.po" files in libvirt
GIT will be overwritten and lost the next time content is imported from Zanata.

The master "libvirt.pot" file is periodically pushed to Zanata to provide the
translation team with content changes, using

::

$ make push-pot

New translated text is then periodically pulled down from Zanata to update the
minimized po files, using

::

$ make pull-po

Sometimes the translators make mistakes, most commonly with handling printf
format specifiers. The "pull-po" command re-generates the .gmo files to try to
identify such mistakes. If a mistake is made, the broken msgstr should be
deleted in the local "$LANG.mini.po" file, and the Zanata web interface used
to reject the translation so that the broken msgstr isn't pulled down next time.

After pulling down new content the diff should be examined to look for any
obvious mistakes that are not caught automatically. There have been bugs in
Zanata tools which caused messges to go missing, so pay particular attention to
diffs showing deletions where the msgid still exists in libvirt.pot
The libvirt GIT repository stores the master "libvirt.pot" file, which is to be
refreshed at time of feature freeze.

The "po" files stored in GIT have source locations removed in order to cut down
on storage size, by eliminating information already present in the "pot" file.
All files are stored with strings sorted in alphabetical order rather than
source location order, to minimize movement of strings when source locations
change.

The "po" files are to be EXCLUSIVELY UPDATED by merge requests sent from the
Fedora Weblate service. Other contributors MUST NEVER send changes which touch
the "po" file content, as that will create merge conflicts for Weblate. IOW any
bug fixes to translations should be made via the Weblate application UI.

After the "pot" file in libvirt GIT, Weblate will automatically run "msgmerge"
to update the "po" files itself and send back a merge request with the changes.

Translation updates made in the Weblate Web UI will be committed to its fork of
the GIT repo once a day. These commits will be submitted back to the master GIT
repo via merge requests. If a merge request from Weblate is already open,
commits will be added to this existing merge request. Weblate will take care of
rebasing whenever changes happen in Git master. In order to avoid having to do
translations merges 30 times a month, merge requests from Weblate will usually
be left open until feature freeze arrives. During the freeze period, they will
be accepted more promptly to ensure they make it into the new release.

+ 21
- 12
AUTHORS View File

@@ -7,55 +7,56 @@ Daniel Veillard <veillard@redhat.com> or <daniel@veillard.com>

The primary maintainers and people with commit access rights:

Alex Jia <ajia@redhat.com>
Andrea Bolognani <abologna@redhat.com>
Cédric Bosdonnat <cbosdonnat@suse.com>
Christian Ehrhardt <christian.ehrhardt@canonical.com>
Christophe Fergeau <cfergeau@redhat.com>
Claudio Bley <claudio.bley@gmail.com>
Cole Robinson <crobinso@redhat.com>
Daniel P. Berrangé <berrange@redhat.com>
Daniel Veillard <veillard@redhat.com>
Doug Goldstein <cardoe@gentoo.org>
Eric Blake <eblake@redhat.com>
Erik Skultety <eskultet@redhat.com>
Fabiano Fidêncio <fidencio@redhat.com>
Gao Feng <gaofeng@cn.fujitsu.com>
Guido Günther <agx@sigxcpu.org>
Ján Tomko <jtomko@redhat.com>
Jim Fehlig <jfehlig@suse.com>
Jiří Denemark <jdenemar@redhat.com>
John Ferlan <jferlan@redhat.com>
Katerina Koukiou <kkoukiou@redhat.com>
Laine Stump <laine@redhat.com>
Mark McLoughlin <markmc@redhat.com>
Martin Kletzander <mkletzan@redhat.com>
Matthias Bolte <matthias.bolte@googlemail.com>
Maxim Nestratov <mnestratov@virtuozzo.com>
Michal Prívozník <mprivozn@redhat.com>
Nikolay Shirokovskiy <nshirokovskiy@virtuozzo.com>
Pavel Hrdina <phrdina@redhat.com>
Peter Krempa <pkrempa@redhat.com>
Pino Toscano <ptoscano@redhat.com>
Richard W.M. Jones <rjones@redhat.com>
Roman Bogorodskiy <bogorodskiy@gmail.com>
Stefan Berger <stefanb@us.ibm.com>
Wen Congyang <wency@cn.fujitsu.com>

Previous maintainers:

Alex Jia <ajia@redhat.com>
Anthony Liguori <aliguori@us.ibm.com>
Atsushi SAKAI <sakaia@jp.fujitsu.com>
Chris Lalancette <clalance@redhat.com>
Claudio Bley <claudio.bley@gmail.com>
Dan Smith <danms@us.ibm.com>
Dave Allan <dallan@redhat.com>
Dave Leskovec <dlesko@linux.vnet.ibm.com>
Dmitry Guryanov <dguryanov@parallels.com>
Doug Goldstein <cardoe@gentoo.org>
Gao Feng <gaofeng@cn.fujitsu.com>
Guannan Ren <gren@redhat.com>
Jim Meyering <meyering@redhat.com>
John Ferlan <jferlan@redhat.com>
John Levon <john.levon@sun.com>
Justin Clift <jclift@redhat.com>
Karel Zak <kzak@redhat.com>
Katerina Koukiou <kkoukiou@redhat.com>
Mark McLoughlin <markmc@redhat.com>
Matthias Bolte <matthias.bolte@googlemail.com>
Maxim Nestratov <mnestratov@virtuozzo.com>
Osier Yang <jyang@redhat.com>
Stefan Berger <stefanb@us.ibm.com>
Wen Congyang <wency@cn.fujitsu.com>

Patches have also been contributed by:

@@ -95,6 +96,7 @@ Tatsuro Enokura <fj7716hz@aa.jp.fujitsu.com>
Adam Litke <agl@us.ibm.com>
Adam Walters <adam@pandorasboxen.com>
Adrian Brzezinski <adrian.brzezinski@eo.pl>
Akarshan Biswas <akarshan.biswas@gmail.com>
Alan Pevec <apevec@redhat.com>
Ales Musil <amusil@redhat.com>
Alex Williamson <alex.williamson@redhat.com>
@@ -137,6 +139,7 @@ Beat Jörg <Beat.Joerg@ssatr.ch>
Ben Gray <ben.r.gray@gmail.com>
Benjamin Cama <benoar@dolka.fr>
Bharata B Rao <bharata@linux.vnet.ibm.com>
Bihong Yu <yubihong@huawei.com>
Bing Bu Cao <mars@linux.vnet.ibm.com>
Bing Niu <bing.niu@intel.com>
Bjoern Walk <bwalk@linux.ibm.com>
@@ -225,6 +228,7 @@ Dipankar Sarma <dipankar@in.ibm.com>
Dirk Herrendoerfer <d.herrendoerfer@herrendoerfer.name>
Dmitry Andreev <dandreev@virtuozzo.com>
Dmitry Mishin <dim@virtuozzo.com>
Dmitry Nesterenko <dmitry.nesterenko@virtuozzo.com>
Dominick Grift <dac.override@gmail.com>
Dominik Perpeet <dperpeet@redhat.com>
Don Dugger <n0ano@n0ano.com>
@@ -301,6 +305,7 @@ Huanle Han <hanxueluo@gmail.com>
Huaqiang <huaqiang.wang@intel.com>
Ian Campbell <Ian.Campbell@citrix.com>
Ian Campbell <ian.campbell@citrix.com>
Ian Jackson <ian.jackson@eu.citrix.com>
Ian Main <imain@redhat.com>
Igor Gnatenko <ignatenkobrain@fedoraproject.org>
Ilias Stamatis <stamatis.iliass@gmail.com>
@@ -354,6 +359,7 @@ Josh Stone <jistone@redhat.com>
Jovanka Gulicoska <jovanka.gulicoska@gmail.com>
Juan Hernandez <jhernand@redhat.com>
Juerg Haefliger <juerg.haefliger@hp.com>
Julien Humbert <julroy67@gmail.com>
Julio Faracco <jcfaracco@gmail.com>
Jun Koi <junkoi2004@gmail.com>
KAMEZAWA Hiroyuki <kamezawa.hiroyu@jp.fujitsu.com>
@@ -430,6 +436,7 @@ Maximilian Wilhelm <max@rfc2324.org>
Maxiwell S. Garcia <maxiwell@linux.ibm.com>
Maya Rashish <coypu@sdf.org>
Mehdi Abaakouk <sileht@redhat.com>
Menno Lageman <menno.lageman@oracle.com>
Michael Avdienko <whitearchey@gmail.com>
Michael Chapman <mike@very.puzzling.org>
Michael Ellerman <michael@ellerman.id.au>
@@ -482,6 +489,7 @@ Paolo Smiraglia <paolo.smiraglia@gmail.com>
Patrice LACHANCE <patlachance@gmail.com>
Patrick Dignan <pat_dignan@dell.com>
Paul Eggert <eggert@cs.ucla.edu>
Paulo de Rezende Pinatti <ppinatti@linux.ibm.com>
Pavel Boldin <pboldin@mirantis.com>
Pavel Fedin <p.fedin@samsung.com>
Pavel Glushchak <pglushchak@virtuozzo.com>
@@ -497,7 +505,6 @@ Peter Robinson <pbrobinson@gmail.com>
Phil Petty <phpetty@cisco.com>
Philipp Hahn <hahn@univention.de>
Pieter Hollants <pieter@hollants.com>
Pino Toscano <ptoscano@redhat.com>
Pradipta Kr. Banerjee <bpradip@in.ibm.com>
Pradipta Kr. Banerjee <pradipta.banerjee@gmail.com>
Prafull <talep158@gmail.com>
@@ -557,6 +564,7 @@ Serge Hallyn <serge.hallyn@ubuntu.com>
Sergey Bronnikov <sergeyb@openvz.org>
Sergey Fionov <fionov@gmail.com>
Shahar Klein <shaharklein@yahoo.com>
Shalini Chellathurai Saroja <shalini@linux.ibm.com>
Shalini Chellathurai Saroja <shalini@linux.vnet.ibm.com>
Shanzhi Yu <shyu@redhat.com>
ShaoHe Feng <shaohe.feng@intel.com>
@@ -639,6 +647,7 @@ Wang Yechao <wang.yechao255@zte.com.cn>
Wang Yufei (James) <james.wangyufei@huawei.com>
Wangjing (King, Euler) <king.wang@huawei.com>
Wangrui (K) <moon.wangrui@huawei.com>
Weblate <noreply@weblate.org>
Wei Huang <wei@redhat.com>
Wei Jiangang <weijg.fnst@cn.fujitsu.com>
Wei Liu <wei.liu2@citrix.com>


+ 12
- 11
AUTHORS.in View File

@@ -7,55 +7,56 @@ Daniel Veillard <veillard@redhat.com> or <daniel@veillard.com>

The primary maintainers and people with commit access rights:

Alex Jia <ajia@redhat.com>
Andrea Bolognani <abologna@redhat.com>
Cédric Bosdonnat <cbosdonnat@suse.com>
Christian Ehrhardt <christian.ehrhardt@canonical.com>
Christophe Fergeau <cfergeau@redhat.com>
Claudio Bley <claudio.bley@gmail.com>
Cole Robinson <crobinso@redhat.com>
Daniel P. Berrangé <berrange@redhat.com>
Daniel Veillard <veillard@redhat.com>
Doug Goldstein <cardoe@gentoo.org>
Eric Blake <eblake@redhat.com>
Erik Skultety <eskultet@redhat.com>
Fabiano Fidêncio <fidencio@redhat.com>
Gao Feng <gaofeng@cn.fujitsu.com>
Guido Günther <agx@sigxcpu.org>
Ján Tomko <jtomko@redhat.com>
Jim Fehlig <jfehlig@suse.com>
Jiří Denemark <jdenemar@redhat.com>
John Ferlan <jferlan@redhat.com>
Katerina Koukiou <kkoukiou@redhat.com>
Laine Stump <laine@redhat.com>
Mark McLoughlin <markmc@redhat.com>
Martin Kletzander <mkletzan@redhat.com>
Matthias Bolte <matthias.bolte@googlemail.com>
Maxim Nestratov <mnestratov@virtuozzo.com>
Michal Prívozník <mprivozn@redhat.com>
Nikolay Shirokovskiy <nshirokovskiy@virtuozzo.com>
Pavel Hrdina <phrdina@redhat.com>
Peter Krempa <pkrempa@redhat.com>
Pino Toscano <ptoscano@redhat.com>
Richard W.M. Jones <rjones@redhat.com>
Roman Bogorodskiy <bogorodskiy@gmail.com>
Stefan Berger <stefanb@us.ibm.com>
Wen Congyang <wency@cn.fujitsu.com>

Previous maintainers:

Alex Jia <ajia@redhat.com>
Anthony Liguori <aliguori@us.ibm.com>
Atsushi SAKAI <sakaia@jp.fujitsu.com>
Chris Lalancette <clalance@redhat.com>
Claudio Bley <claudio.bley@gmail.com>
Dan Smith <danms@us.ibm.com>
Dave Allan <dallan@redhat.com>
Dave Leskovec <dlesko@linux.vnet.ibm.com>
Dmitry Guryanov <dguryanov@parallels.com>
Doug Goldstein <cardoe@gentoo.org>
Gao Feng <gaofeng@cn.fujitsu.com>
Guannan Ren <gren@redhat.com>
Jim Meyering <meyering@redhat.com>
John Ferlan <jferlan@redhat.com>
John Levon <john.levon@sun.com>
Justin Clift <jclift@redhat.com>
Karel Zak <kzak@redhat.com>
Katerina Koukiou <kkoukiou@redhat.com>
Mark McLoughlin <markmc@redhat.com>
Matthias Bolte <matthias.bolte@googlemail.com>
Maxim Nestratov <mnestratov@virtuozzo.com>
Osier Yang <jyang@redhat.com>
Stefan Berger <stefanb@us.ibm.com>
Wen Congyang <wency@cn.fujitsu.com>

Patches have also been contributed by:



+ 2
- 2
ChangeLog View File

@@ -7,9 +7,9 @@ archives.
If you're interested in the full list of changes made to libvirt since
the project was started, you can clone the git repository from

https://libvirt.org/git/libvirt.git
https://gitlab.com/libvirt/libvirt/

and browse them locally using your favorite git history viewer or,
alternatively, browse them online at

https://libvirt.org/git/?p=libvirt.git;a=log
https://gitlab.com/libvirt/libvirt/-/commits/master

+ 1
- 22
Makefile.am View File

@@ -46,6 +46,7 @@ EXTRA_DIST = \
README.rst \
AUTHORS.in \
CONTRIBUTING.rst \
NEWS.rst \
scripts/apibuild.py \
scripts/augeas-gentest.py \
build-aux/check-spacing.pl \
@@ -66,10 +67,8 @@ EXTRA_DIST = \
scripts/header-ifdef.py \
scripts/hvsupport.py \
scripts/hyperv_wmi_generator.py \
scripts/minimize-po.py \
scripts/mock-noinline.py \
scripts/prohibit-duplicate-header.py \
scripts/reformat-news.py \
scripts/test-wrap-argv.py \
build-aux/syntax-check.mk \
build-aux/useless-if-before-free \
@@ -83,26 +82,6 @@ EXTRA_DIST = \
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = libvirt.pc libvirt-qemu.pc libvirt-lxc.pc libvirt-admin.pc

NEWS: \
$(srcdir)/docs/news.xml \
$(srcdir)/docs/news-ascii.xsl \
$(top_srcdir)/scripts/reformat-news.py
$(AM_V_GEN) \
if [ -x $(XSLTPROC) ]; then \
$(XSLTPROC) --nonet \
$(srcdir)/docs/news-ascii.xsl \
$(srcdir)/docs/news.xml \
>$@-tmp \
|| { rm -f $@-tmp; exit 1; }; \
$(RUNUTF8) $(PYTHON) $(top_srcdir)/scripts/reformat-news.py $@-tmp >$@ \
|| { rm -f $@-tmp; exit 1; }; \
rm -f $@-tmp; \
fi
EXTRA_DIST += \
$(srcdir)/docs/news.xml \
$(srcdir)/docs/news-ascii.xsl \
$(NULL)

rpm: clean
@(unset CDPATH ; $(MAKE) dist && rpmbuild -ta $(distdir).tar.xz)



+ 50
- 38
Makefile.in View File

@@ -294,7 +294,7 @@ am__DIST_COMMON = $(srcdir)/.color_coded.in \
$(top_srcdir)/build-aux/install-sh \
$(top_srcdir)/build-aux/ltmain.sh \
$(top_srcdir)/build-aux/missing ABOUT-NLS AUTHORS COPYING \
COPYING.LESSER ChangeLog INSTALL NEWS README build-aux/compile \
COPYING.LESSER ChangeLog INSTALL README build-aux/compile \
build-aux/config.guess build-aux/config.sub \
build-aux/install-sh build-aux/ltmain.sh build-aux/missing
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
@@ -467,6 +467,7 @@ LVS = @LVS@
LV_LIBTOOL_OBJDIR = @LV_LIBTOOL_OBJDIR@
MAKEINFO = @MAKEINFO@
MANIFEST_TOOL = @MANIFEST_TOOL@
MDEVCTL = @MDEVCTL@
MINGW_EXTRA_LDFLAGS = @MINGW_EXTRA_LDFLAGS@
MKDIR_P = @MKDIR_P@
MKFS = @MKFS@
@@ -640,27 +641,54 @@ SUBDIRS = . include/libvirt src tools docs \
tests po examples

ACLOCAL_AMFLAGS = -I m4
EXTRA_DIST = config-post.h libvirt.spec libvirt.spec.in \
mingw-libvirt.spec.in libvirt.pc.in libvirt-qemu.pc.in \
libvirt-lxc.pc.in libvirt-admin.pc.in Makefile.nonreentrant \
autogen.sh GNUmakefile run.in README.rst AUTHORS.in \
CONTRIBUTING.rst scripts/apibuild.py scripts/augeas-gentest.py \
build-aux/check-spacing.pl scripts/check-aclperms.py \
scripts/check-aclrules.py scripts/check-drivername.py \
scripts/check-driverimpls.py scripts/check-file-access.py \
scripts/check-remote-protocol.py scripts/check-symfile.py \
scripts/check-symsorting.py scripts/dtrace2systemtap.py \
scripts/esx_vi_generator.py scripts/genaclperms.py \
scripts/genpolkit.py scripts/gensystemtap.py \
scripts/group-qemu-caps.py scripts/header-ifdef.py \
scripts/hvsupport.py scripts/hyperv_wmi_generator.py \
scripts/minimize-po.py scripts/mock-noinline.py \
scripts/prohibit-duplicate-header.py scripts/reformat-news.py \
scripts/test-wrap-argv.py build-aux/syntax-check.mk \
build-aux/useless-if-before-free build-aux/vc-list-files \
ci/Makefile ci/build.sh ci/list-images.sh ci/prepare.sh \
$(NULL) $(srcdir)/docs/news.xml $(srcdir)/docs/news-ascii.xsl \
$(NULL)
EXTRA_DIST = \
config-post.h \
libvirt.spec libvirt.spec.in \
mingw-libvirt.spec.in \
libvirt.pc.in \
libvirt-qemu.pc.in \
libvirt-lxc.pc.in \
libvirt-admin.pc.in \
Makefile.nonreentrant \
autogen.sh \
GNUmakefile \
run.in \
README.rst \
AUTHORS.in \
CONTRIBUTING.rst \
NEWS.rst \
scripts/apibuild.py \
scripts/augeas-gentest.py \
build-aux/check-spacing.pl \
scripts/check-aclperms.py \
scripts/check-aclrules.py \
scripts/check-drivername.py \
scripts/check-driverimpls.py \
scripts/check-file-access.py \
scripts/check-remote-protocol.py \
scripts/check-symfile.py \
scripts/check-symsorting.py \
scripts/dtrace2systemtap.py \
scripts/esx_vi_generator.py \
scripts/genaclperms.py \
scripts/genpolkit.py \
scripts/gensystemtap.py \
scripts/group-qemu-caps.py \
scripts/header-ifdef.py \
scripts/hvsupport.py \
scripts/hyperv_wmi_generator.py \
scripts/mock-noinline.py \
scripts/prohibit-duplicate-header.py \
scripts/test-wrap-argv.py \
build-aux/syntax-check.mk \
build-aux/useless-if-before-free \
build-aux/vc-list-files \
ci/Makefile \
ci/build.sh \
ci/list-images.sh \
ci/prepare.sh \
$(NULL)

pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = libvirt.pc libvirt-qemu.pc libvirt-lxc.pc libvirt-admin.pc
MAINTAINERCLEANFILES = .git-module-status
@@ -1207,22 +1235,6 @@ uninstall-am: uninstall-pkgconfigDATA
XZ_OPT ?= -v -T0
export XZ_OPT

NEWS: \
$(srcdir)/docs/news.xml \
$(srcdir)/docs/news-ascii.xsl \
$(top_srcdir)/scripts/reformat-news.py
$(AM_V_GEN) \
if [ -x $(XSLTPROC) ]; then \
$(XSLTPROC) --nonet \
$(srcdir)/docs/news-ascii.xsl \
$(srcdir)/docs/news.xml \
>$@-tmp \
|| { rm -f $@-tmp; exit 1; }; \
$(RUNUTF8) $(PYTHON) $(top_srcdir)/scripts/reformat-news.py $@-tmp >$@ \
|| { rm -f $@-tmp; exit 1; }; \
rm -f $@-tmp; \
fi

rpm: clean
@(unset CDPATH ; $(MAKE) dist && rpmbuild -ta $(distdir).tar.xz)



+ 0
- 2836
NEWS
File diff suppressed because it is too large
View File


+ 4156
- 0
NEWS.rst
File diff suppressed because it is too large
View File


+ 3
- 0
README View File

@@ -7,6 +7,9 @@
.. image:: https://bestpractices.coreinfrastructure.org/projects/355/badge
:target: https://bestpractices.coreinfrastructure.org/projects/355
:alt: CII Best Practices
.. image:: https://translate.fedoraproject.org/widgets/libvirt/-/libvirt/svg-badge.svg
:target: https://translate.fedoraproject.org/engage/libvirt/
:alt: Translation status

==============================
Libvirt API for virtualization


+ 3
- 0
README.rst View File

@@ -7,6 +7,9 @@
.. image:: https://bestpractices.coreinfrastructure.org/projects/355/badge
:target: https://bestpractices.coreinfrastructure.org/projects/355
:alt: CII Best Practices
.. image:: https://translate.fedoraproject.org/widgets/libvirt/-/libvirt/svg-badge.svg
:target: https://translate.fedoraproject.org/engage/libvirt/
:alt: Translation status

==============================
Libvirt API for virtualization


+ 10
- 1
autogen.sh View File

@@ -1,5 +1,10 @@
#!/bin/sh
# Run this to generate all the initial makefiles, etc.
#
# THe following options must come first. All other or subsequent
# arguments are passed to configure:
# --no-git skip `git submodule update --init`

test -n "$srcdir" || srcdir=$(dirname "$0")
test -n "$srcdir" || srcdir=.

@@ -13,7 +18,11 @@ cd "$srcdir"
exit 1
}

git submodule update --init || exit 1
if [ "x$1" = x--no-git ]; then
shift
else
git submodule update --init || exit 1
fi

autoreconf --verbose --force --install || exit 1



+ 1
- 1
build-aux/syntax-check.mk View File

@@ -2015,7 +2015,7 @@ exclude_file_name_regexp--sc_prohibit_close = \
(\.p[yl]$$|\.spec\.in$$|^docs/|^(src/util/vir(file|event)\.c|src/libvirt-stream\.c|tests/(vir.+mock\.c|commandhelper\.c|qemusecuritymock\.c)|tools/nss/libvirt_nss_(leases|macs)\.c)$$)

exclude_file_name_regexp--sc_prohibit_empty_lines_at_EOF = \
(^tests/(virhostcpu|virpcitest)data/|docs/js/.*\.js|docs/fonts/.*\.woff|\.diff|tests/virconfdata/no-newline\.conf$$)
(^tests/(nodedevmdevctl|virhostcpu|virpcitest)data/|docs/js/.*\.js|docs/fonts/.*\.woff|\.diff|tests/virconfdata/no-newline\.conf$$)

exclude_file_name_regexp--sc_prohibit_fork_wrappers = \
(^(src/(util/(vircommand|virdaemon)|lxc/lxc_controller)|tests/testutils)\.c$$)


+ 9
- 7
ci/Makefile View File

@@ -48,9 +48,9 @@ CI_PREPARE_SCRIPT = $(CI_ROOTDIR)/prepare.sh
CI_BUILD_SCRIPT = $(CI_ROOTDIR)/build.sh

# Location of the container images we're going to pull
# Can be useful to overridde to use a locally built
# Can be useful to override to use a locally built
# image instead
CI_IMAGE_PREFIX = quay.io/libvirt/buildenv-libvirt-
CI_IMAGE_PREFIX = registry.gitlab.com/libvirt/libvirt/ci-

# The default tag is ':latest' but if the container
# repo above uses different conventions this can override it
@@ -243,11 +243,11 @@ ci-list-images:
@echo
@echo "Available x86 container images:"
@echo
@sh list-images.sh "$(CI_ENGINE)" "$(CI_IMAGE_PREFIX)" | grep -v cross
@sh list-images.sh "$(CI_IMAGE_PREFIX)" | grep -v cross
@echo
@echo "Available cross-compiler container images:"
@echo
@sh list-images.sh "$(CI_ENGINE)" "$(CI_IMAGE_PREFIX)" | grep cross
@sh list-images.sh "$(CI_IMAGE_PREFIX)" | grep cross
@echo

ci-help:
@@ -263,7 +263,9 @@ ci-help:
@echo
@echo "Available make variables:"
@echo
@echo " CI_CLEAN=0 - do not delete '$(CI_SCRATCHDIR)' after completion"
@echo " CI_REUSE=1 - re-use existing '$(CI_SCRATCHDIR)' content"
@echo " CI_ENGINE=auto - container engine to use (podman, docker)"
@echo " CI_CLEAN=0 - do not delete '$(CI_SCRATCHDIR)' after completion"
@echo " CI_REUSE=1 - re-use existing '$(CI_SCRATCHDIR)' content"
@echo " CI_ENGINE=auto - container engine to use (podman, docker)"
@echo " CI_CONFIGURE_ARGS= - extra arguments passed to configure"
@echo " CI_MAKE_ARGS= - extra arguments passed to make, e.g. space delimited list of targets"
@echo

+ 6
- 18
ci/list-images.sh View File

@@ -1,26 +1,14 @@
#!/bin/sh

engine="$1"
prefix="$2"
prefix="${1##registry.gitlab.com/}"

do_podman() {
# Podman freaks out if the search term ends with a dash, which ours
# by default does, so let's strip it. The repository name is the
# second field in the output, and it already starts with the registry
podman search --limit 100 "${prefix%-}" | while read _ repo _; do
echo "$repo"
done
}
PROJECT_ID=192693

do_docker() {
# Docker doesn't include the registry name in the output, so we have
# to add it. The repository name is the first field in the output
registry="${prefix%%/*}"
docker search --limit 100 "$prefix" | while read repo _; do
echo "$registry/$repo"
done
all_repos() {
curl -s "https://gitlab.com/api/v4/projects/$PROJECT_ID/registry/repositories?per_page=100" \
| tr , '\n' | grep '"path":' | sed 's,"path":",,g;s,"$,,g'
}

"do_$engine" | grep "^$prefix" | sed "s,^$prefix,,g" | while read repo; do
all_repos | grep "^$prefix" | sed "s,^$prefix,,g" | while read repo; do
echo " $repo"
done | sort -u

+ 3
- 0
config.h.in View File

@@ -560,6 +560,9 @@
<sysmacros.h>. */
#undef MAJOR_IN_SYSMACROS

/* Location or name of the mdevctl program */
#undef MDEVCTL

/* Location or name of the mkfs program */
#undef MKFS



+ 57
- 10
configure View File

@@ -1,6 +1,6 @@
#! /bin/sh
# Guess values for system-dependent variables and create Makefiles.
# Generated by GNU Autoconf 2.69 for libvirt 6.4.0.
# Generated by GNU Autoconf 2.69 for libvirt 6.5.0.
#
# Report bugs to <libvir-list@redhat.com>.
#
@@ -590,8 +590,8 @@ MAKEFLAGS=
# Identity of this package.
PACKAGE_NAME='libvirt'
PACKAGE_TARNAME='libvirt'
PACKAGE_VERSION='6.4.0'
PACKAGE_STRING='libvirt 6.4.0'
PACKAGE_VERSION='6.5.0'
PACKAGE_STRING='libvirt 6.5.0'
PACKAGE_BUGREPORT='libvir-list@redhat.com'
PACKAGE_URL='https://libvirt.org'

@@ -887,6 +887,7 @@ EBTABLES_PATH
IP6TABLES_PATH
IPTABLES_PATH
IP_PATH
MDEVCTL
ADDR2LINE
SCRUB
OVSVSCTL
@@ -1925,7 +1926,7 @@ if test "$ac_init_help" = "long"; then
# Omit some internal or obsolete options to make the list less imposing.
# This message is too long to be a string in the A/UX 3.1 sh.
cat <<_ACEOF
\`configure' configures libvirt 6.4.0 to adapt to many kinds of systems.
\`configure' configures libvirt 6.5.0 to adapt to many kinds of systems.

Usage: $0 [OPTION]... [VAR=VALUE]...

@@ -1995,7 +1996,7 @@ fi

if test -n "$ac_init_help"; then
case $ac_init_help in
short | recursive ) echo "Configuration of libvirt 6.4.0:";;
short | recursive ) echo "Configuration of libvirt 6.5.0:";;
esac
cat <<\_ACEOF

@@ -2329,7 +2330,7 @@ fi
test -n "$ac_init_help" && exit $ac_status
if $ac_init_version; then
cat <<\_ACEOF
libvirt configure 6.4.0
libvirt configure 6.5.0
generated by GNU Autoconf 2.69

Copyright (C) 2012 Free Software Foundation, Inc.
@@ -3038,7 +3039,7 @@ cat >config.log <<_ACEOF
This file contains any messages produced by compilers while
running configure, to aid debugging if configure makes a mistake.

It was created by libvirt $as_me 6.4.0, which was
It was created by libvirt $as_me 6.5.0, which was
generated by GNU Autoconf 2.69. Invocation command line was

$ $0 $@
@@ -3938,7 +3939,7 @@ fi

# Define the identity of the package.
PACKAGE='libvirt'
VERSION='6.4.0'
VERSION='6.5.0'


cat >>confdefs.h <<_ACEOF
@@ -25724,6 +25725,47 @@ $as_echo "no" >&6; }
fi


# Extract the first word of "mdevctl", so it can be a program name with args.
set dummy mdevctl; ac_word=$2
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
$as_echo_n "checking for $ac_word... " >&6; }
if ${ac_cv_path_MDEVCTL+:} false; then :
$as_echo_n "(cached) " >&6
else
case $MDEVCTL in
[\\/]* | ?:[\\/]*)
ac_cv_path_MDEVCTL="$MDEVCTL" # Let the user override the test with a path.
;;
*)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $LIBVIRT_SBIN_PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_path_MDEVCTL="$as_dir/$ac_word$ac_exec_ext"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS

test -z "$ac_cv_path_MDEVCTL" && ac_cv_path_MDEVCTL="mdevctl"
;;
esac
fi
MDEVCTL=$ac_cv_path_MDEVCTL
if test -n "$MDEVCTL"; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $MDEVCTL" >&5
$as_echo "$MDEVCTL" >&6; }
else
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
$as_echo "no" >&6; }
fi




cat >>confdefs.h <<_ACEOF
@@ -25781,6 +25823,11 @@ cat >>confdefs.h <<_ACEOF
_ACEOF


cat >>confdefs.h <<_ACEOF
#define MDEVCTL "$MDEVCTL"
_ACEOF


# Extract the first word of "ip", so it can be a program name with args.
set dummy ip; ac_word=$2
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
@@ -33200,7 +33247,7 @@ cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
# report actual input values of CONFIG_FILES etc. instead of their
# values after options handling.
ac_log="
This file was extended by libvirt $as_me 6.4.0, which was
This file was extended by libvirt $as_me 6.5.0, which was
generated by GNU Autoconf 2.69. Invocation command line was

CONFIG_FILES = $CONFIG_FILES
@@ -33271,7 +33318,7 @@ _ACEOF
cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
ac_cs_version="\\
libvirt config.status 6.4.0
libvirt config.status 6.5.0
configured by $0, generated by GNU Autoconf 2.69,
with options \\"\$ac_cs_config\\"



+ 1
- 1
configure.ac View File

@@ -16,7 +16,7 @@ dnl You should have received a copy of the GNU Lesser General Public
dnl License along with this library. If not, see
dnl <http://www.gnu.org/licenses/>.

AC_INIT([libvirt], [6.4.0], [libvir-list@redhat.com], [], [https://libvirt.org])
AC_INIT([libvirt], [6.5.0], [libvir-list@redhat.com], [], [https://libvirt.org])

if test $srcdir = "."
then


+ 11
- 16
docs/Makefile.am View File

@@ -316,16 +316,18 @@ manpages/virkeyname-%.rst: $(top_srcdir)/src/keycodemapdb/data/keymaps.csv \
manpagesdir = $(HTML_DIR)/manpages
manpages_DATA = $(manpages_html)

# Generate hvsupport.html and news.html first, since they take one extra step.
# Generate hvsupport.html first, since it takes one extra step.
dot_html_generated_in = \
hvsupport.html.in \
news.html.in
$(NULL)
dot_html_in = \
$(notdir $(wildcard $(srcdir)/*.html.in))
dot_rst = \
$(notdir $(wildcard $(srcdir)/*.rst))
dot_rst_html_in = \
$(dot_rst:%.rst=%.html)
$(dot_rst:%.rst=%.html.in) \
news.html.in \
$(NULL)
dot_html = \
$(dot_html_generated_in:%.html.in=%.html) \
$(dot_html_in:%.html.in=%.html) \
@@ -405,19 +407,6 @@ hvsupport.html.in: $(top_srcdir)/scripts/hvsupport.py $(api_DATA) \
$(AM_V_GEN)$(RUNUTF8) $(PYTHON) $(top_srcdir)/scripts/hvsupport.py \
$(top_srcdir) $(top_builddir) > $@ || { rm $@ && exit 1; }

news.html.in: \
$(srcdir)/news.xml \
$(srcdir)/news-html.xsl
$(AM_V_GEN)$(XSLTPROC) --nonet \
$(srcdir)/news-html.xsl \
$(srcdir)/news.xml \
>$@ \
|| { rm -f $@; exit 1; };
EXTRA_DIST += \
$(srcdir)/news.xml \
$(srcdir)/news.rng \
$(srcdir)/news-html.xsl

%.png: %.fig
convert -rotate 90 $< $@

@@ -428,6 +417,12 @@ manpages/%.html.in: manpages/%.rst
-e 's|RUNSTATEDIR|$(runstatedir)|g' | \
$(RST2HTML) --strict > $@ || { rm $@ && exit 1; }

news.html.in: $(top_srcdir)/NEWS.rst
$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
$(RST2HTML) --strict $< > $@ || { rm $@ && exit 1; }

CLEANFILES += news.html.in

%.html.in: %.rst
$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
$(RST2HTML) --strict $< > $@ || { rm $@ && exit 1; }


+ 23
- 19
docs/Makefile.in View File

@@ -403,6 +403,7 @@ LVS = @LVS@
LV_LIBTOOL_OBJDIR = @LV_LIBTOOL_OBJDIR@
MAKEINFO = @MAKEINFO@
MANIFEST_TOOL = @MANIFEST_TOOL@
MDEVCTL = @MDEVCTL@
MINGW_EXTRA_LDFLAGS = @MINGW_EXTRA_LDFLAGS@
MKDIR_P = @MKDIR_P@
MKFS = @MKFS@
@@ -757,10 +758,10 @@ man8_MANS = $(manpages8_rst:%.rst=%.8)
manpagesdir = $(HTML_DIR)/manpages
manpages_DATA = $(manpages_html)

# Generate hvsupport.html and news.html first, since they take one extra step.
# Generate hvsupport.html first, since it takes one extra step.
dot_html_generated_in = \
hvsupport.html.in \
news.html.in
$(NULL)

dot_html_in = \
$(notdir $(wildcard $(srcdir)/*.html.in))
@@ -769,7 +770,9 @@ dot_rst = \
$(notdir $(wildcard $(srcdir)/*.rst))

dot_rst_html_in = \
$(dot_rst:%.rst=%.html)
$(dot_rst:%.rst=%.html.in) \
news.html.in \
$(NULL)

dot_html = \
$(dot_html_generated_in:%.html.in=%.html) \
@@ -796,18 +799,24 @@ fig = \

schemadir = $(pkgdatadir)/schemas
schema_DATA = $(wildcard $(srcdir)/schemas/*.rng)
EXTRA_DIST = site.xsl subsite.xsl newapi.xsl page.xsl wrapstring.xsl \
$(dot_html_in) $(dot_rst) $(apipng) $(fig) $(assets) \
$(javascript) $(logofiles) $(internals_html_in) \
$(internals_rst) $(fonts) $(kbase_html_in) $(kbase_rst) \
$(manpages_rst) aclperms.htmlinc $(schema_DATA) \
$(srcdir)/news.xml $(srcdir)/news.rng $(srcdir)/news-html.xsl
EXTRA_DIST = \
site.xsl subsite.xsl newapi.xsl page.xsl \
wrapstring.xsl \
$(dot_html_in) $(dot_rst) $(apipng) \
$(fig) $(assets) \
$(javascript) $(logofiles) \
$(internals_html_in) $(internals_rst) $(fonts) \
$(kbase_html_in) $(kbase_rst) \
$(manpages_rst) \
aclperms.htmlinc \
$(schema_DATA)

acl_generated = aclperms.htmlinc
CLEANFILES = $(dot_html) $(apihtml) $(apiadminhtml) $(apiqemuhtml) \
$(apilxchtml) $(internals_html) $(kbase_html) $(manpages_html) \
$(man1_MANS) $(man7_MANS) $(manpages7_rst) $(man8_MANS) \
$(api_DATA) $(dot_html_generated_in) aclperms.htmlinc \
$(APIBUILD_STAMP)
news.html.in $(APIBUILD_STAMP)
timestamp = "$(shell if test -n "$$SOURCE_DATE_EPOCH"; \
then \
date -u --date="@$$SOURCE_DATE_EPOCH"; \
@@ -1458,15 +1467,6 @@ hvsupport.html.in: $(top_srcdir)/scripts/hvsupport.py $(api_DATA) \
$(AM_V_GEN)$(RUNUTF8) $(PYTHON) $(top_srcdir)/scripts/hvsupport.py \
$(top_srcdir) $(top_builddir) > $@ || { rm $@ && exit 1; }

news.html.in: \
$(srcdir)/news.xml \
$(srcdir)/news-html.xsl
$(AM_V_GEN)$(XSLTPROC) --nonet \
$(srcdir)/news-html.xsl \
$(srcdir)/news.xml \
>$@ \
|| { rm -f $@; exit 1; };

%.png: %.fig
convert -rotate 90 $< $@

@@ -1477,6 +1477,10 @@ manpages/%.html.in: manpages/%.rst
-e 's|RUNSTATEDIR|$(runstatedir)|g' | \
$(RST2HTML) --strict > $@ || { rm $@ && exit 1; }

news.html.in: $(top_srcdir)/NEWS.rst
$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
$(RST2HTML) --strict $< > $@ || { rm $@ && exit 1; }

%.html.in: %.rst
$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
$(RST2HTML) --strict $< > $@ || { rm $@ && exit 1; }


+ 1
- 1
docs/aclpolkit.html.in View File

@@ -459,7 +459,7 @@ polkit.addRule(function(action, subject) {

<p>
See
<a href="https://libvirt.org/git/?p=libvirt.git;a=tree;f=examples/polkit;hb=HEAD">source code</a>
<a href="https://gitlab.com/libvirt/libvirt/-/tree/master/examples/polkit">source code</a>
for a more complex example.
</p>



+ 3
- 3
docs/apps.html.in View File

@@ -138,12 +138,12 @@
</dl>

<dl>
<dt><a href="https://wiki.jenkins-ci.org/display/JENKINS/Libvirt+Slaves+Plugin">Jenkins</a></dt>
<dt><a href="https://plugins.jenkins.io/libvirt-slave/">Jenkins</a></dt>
<dd>
This plugin for Jenkins adds a way to control guest domains hosted
on Xen or QEMU/KVM. You configure a Jenkins Slave,
on Xen or QEMU/KVM. You configure a Jenkins Agent,
selecting the guest domain and hypervisor. When you need to build a
job on a specific Slave, its guest domain is started, then the job is
job on a specific Agent, its guest domain is started, then the job is
run. When the build process is finished, the guest domain is shut
down, ready to be used again as required.
</dd>


+ 1
- 1
docs/bindings.html.in View File

@@ -49,7 +49,7 @@
<li>
<p>
<strong>Python</strong>: Libvirt's python bindings are split to a
separate <a href="https://libvirt.org/git/?p=libvirt-python.git">package</a>
separate <a href="https://gitlab.com/libvirt/libvirt-python">package</a>
since version 1.2.0, older versions came with direct support for the
Python language.
</p>


+ 0
- 5
docs/ci.rst View File

@@ -138,11 +138,6 @@ Testing
:target: https://gitlab.com/libvirt/libvirt-ci/pipelines
:alt: libvirt-ci pipeline status

* - libvirt-dockerfiles
- .. image:: https://gitlab.com/libvirt/libvirt-dockerfiles/badges/master/pipeline.svg
:target: https://gitlab.com/libvirt/libvirt-dockerfiles/pipelines
:alt: libvirt-dockerfiles pipeline status

* - libvirt-test-API
- .. image:: https://gitlab.com/libvirt/libvirt-test-API/badges/master/pipeline.svg
:target: https://gitlab.com/libvirt/libvirt-test-API/pipelines


+ 2
- 2
docs/contribute.html.in View File

@@ -42,8 +42,8 @@
<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="http://fedora.zanata.org">Fedora
instance</a> of the Zanata tool. Thus people wishing
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


+ 2
- 23
docs/csharp.html.in View File

@@ -29,36 +29,15 @@
compiling libvirt for windows.
</p>

<!-- 2010-10-19 JC: Commented out until we have C# tarballs to download
<h2><a id="getting">Getting them</a></h2>

<p>
The latest versions of the libvirt C# bindings can be downloaded from:
</p>

<ul>
<li><a href="ftp://libvirt.org/libvirt/csharp/">libvirt.org FTP server</a></li>
<li><a href="https://libvirt.org/sources/csharp/">libvirt.org HTTP server</a></li>
</ul>
-->

<h2><a id="git">GIT source repository</a></h2>
<p>
The C# bindings source code is maintained in a <a
href="http://git-scm.com/">git</a> repository available on
<a href="https://libvirt.org/git/">libvirt.org</a>:
</p>

<pre>
git clone https://libvirt.org/git/libvirt-csharp.git
</pre>

<p>
They can also be browsed online:
<a href="https://gitlab.com/libvirt/libvirt-csharp">gitlab.com</a>:
</p>

<pre>
<a href="https://libvirt.org/git/?p=libvirt-csharp.git;a=summary">https://libvirt.org/git/?p=libvirt-csharp.git;a=summary</a>
git clone https://gitlab.com/libvirt/libvirt-csharp.git
</pre>

<h2><a id="usage">Usage</a></h2>


+ 2
- 10
docs/dbus.html.in View File

@@ -17,19 +17,11 @@
<p>
The D-Bus bindings source code is maintained in a
<a href="https://git-scm.com/">git</a> repository available on
<a href="https://libvirt.org/git/">libvirt.org</a>:
<a href="https://gitlab.com/libvirt/libvirt-dbus">gitlab.com</a>:
</p>

<pre>
git clone https://libvirt.org/git/libvirt-dbus.git
</pre>

<p>
They can also be browsed online:
</p>

<pre>
<a href="https://libvirt.org/git/?p=libvirt-dbus.git">https://libvirt.org/git/?p=libvirt-dbus.git</a>
git clone https://gitlab.com/libvirt/libvirt-dbus.git
</pre>

<h2><a id="usage">Usage</a></h2>


+ 6
- 6
docs/drvqemu.html.in View File

@@ -468,12 +468,12 @@ chmod o+x /path/to/directory
for resource management. It is implemented via a number of "controllers",
each controller covering a specific task/functional area. One of the
available controllers is the "devices" controller, which is able to
setup whitelists of block/character devices that a cgroup should be
allowed to access. If the "devices" controller is mounted on a host,
then libvirt will automatically create a dedicated cgroup for each
QEMU virtual machine and setup the device whitelist so that the QEMU
process can only access shared devices, and explicitly disks images
backed by block devices.
setup access control lists of block/character devices that a cgroup
should be allowed to access. If the "devices" controller is mounted on a
host, then libvirt will automatically create a dedicated cgroup for each
QEMU virtual machine and setup the device access control list so that the
QEMU process can only access shared devices, and explicitly assigned disks
images backed by block devices.
</p>

<p>


+ 3
- 3
docs/firewall.html.in View File

@@ -12,7 +12,7 @@
<li>The virtual network driver
<br /><br />
This provides an isolated bridge device (ie no physical NICs
enslaved). Guest TAP devices are attached to this bridge.
attached). Guest TAP devices are attached to this bridge.
Guests can talk to each other and the host, and optionally the
wider world.
<br /><br />
@@ -46,7 +46,7 @@
</p>
<p>Thus the virtual network driver in libvirt was invented. This takes
the form of an isolated bridge device (ie one with no physical NICs
enslaved). The TAP devices associated with the guest NICs are attached
attached). The TAP devices associated with the guest NICs are attached
to the bridge device. This immediately allows guests on a single host
to talk to each other and to the host OS (modulo host IPtables rules).
</p>
@@ -311,7 +311,7 @@ f5c78134-9da4-0c60-a9f0-fb37bc21ac1f no-other-rarp-traffic
<p>To associate the clean-traffic filter with a guest, edit the
guest XML config and change the <code>&lt;interface&gt;</code> element
to include a <code>&lt;filterref&gt;</code> and also specify the
whitelisted <code>&lt;ip address/&gt;</code> the guest is allowed to
<code>&lt;ip address/&gt;</code> that the guest is allowed to
use:
</p>
<pre>


+ 83
- 6
docs/formatdomain.html.in View File

@@ -479,6 +479,10 @@
&lt;entry&gt;otherappname:more arbitrary data&lt;/entry&gt;
&lt;/oemStrings&gt;
&lt;/sysinfo&gt;
&lt;sysinfo type='fwcfg'&gt;
&lt;entry name='opt/com.example/name'&gt;example value&lt;/entry&gt;
&lt;entry name='opt/com.coreos/config' file='/tmp/provision.ign'/&gt;
&lt;/sysinfo&gt;
...</pre>

<p>
@@ -593,6 +597,34 @@
</dd>
</dl>
</dd>

<dt><code>fwcfg</code></dt>
<dd>
Some hypervisors provide unified way to tweak how firmware configures
itself, or may contain tables to be installed for the guest OS, for
instance boot order, ACPI, SMBIOS, etc. It even allows users to define
their own config blobs. In case of QEMU, these then appear under domain's
sysfs, under <code>/sys/firmware/qemu_fw_cfg</code>. Note, that these
values apply regardless the &lt;smbios/&gt; mode under &lt;os/&gt;.
<span class="since">Since 6.5.0</span>

<pre>
&lt;smbios type='fwcfg'&gt;
&lt;entry name='opt/com.example/name'&gt;example value&lt;/entry&gt;
&lt;entry name='opt/com.coreos/config' file='/tmp/provision.ign'/&gt;
&lt;/smbios&gt;
</pre>

The <code>smbios</code> element can have multiple <code>entry</code>
child elements. Each element then has mandatory <code>name</code>
attribute, which defines the name of the blob and must begin with
<code>"opt/"</code> and to avoid clashing with other names is advised to
be in form <code>"opt/$RFQDN/$name"</code> where <code>$RFQDN</code> is a
reverse fully qualified domain name you control.
Then, the element can either contain the value (to set the blob value
directly), or <code>file</code> attribute (to set the blob value from
the file).
</dd>
</dl>

<h3><a id="elementsCPUAllocation">CPU Allocation</a></h3>
@@ -1490,7 +1522,7 @@
...</pre>

<pre>
&lt;cpu mode='host-passthrough'&gt;
&lt;cpu mode='host-passthrough' migratable='off'&gt;
&lt;cache mode='passthrough'/&gt;
&lt;feature policy='disable' name='lahf_lm'/&gt;
...</pre>
@@ -1639,7 +1671,17 @@
using host-passthrough is dangerous if the source and destination hosts
are not identical in both hardware, QEMU version, microcode version
and configuration. If such a migration is attempted then the guest may
hang or crash upon resuming execution on the destination host.</dd>
hang or crash upon resuming execution on the destination host.
Depending on hypervisor version the virtual CPU may or may not
contain features which may block migration even to an identical host.
<span class="since">Since 6.5.0</span> optional
<code>migratable</code> attribute may be used to explicitly request
such features to be removed from (<code>on</code>) or kept in
(<code>off</code>) the virtual CPU. This attribute does not make
migration to another host safer: even with
<code>migratable='on'</code> migration will be dangerous unless both
hosts are identical as described above.
</dd>
</dl>

Both <code>host-model</code> and <code>host-passthrough</code> modes
@@ -1787,7 +1829,16 @@
<p>
Each <code>cell</code> element specifies a NUMA cell or a NUMA node.
<code>cpus</code> specifies the CPU or range of CPUs that are
part of the node. <code>memory</code> specifies the node memory
part of the node. <span class="since">Since 6.5.0</span> For the qemu
driver, if the emulator binary supports disjointed <code>cpus</code> ranges
in each <code>cell</code>, the sum of all CPUs declared in each <code>cell</code>
will be matched with the maximum number of virtual CPUs declared in the
<code>vcpu</code> element. This is done by filling any remaining CPUs
into the first NUMA <code>cell</code>. Users are encouraged to supply a
complete NUMA topology, where the sum of the NUMA CPUs matches the maximum
virtual CPUs number declared in <code>vcpus</code>, to make the domain
consistent across qemu and libvirt versions.
<code>memory</code> specifies the node memory
in kibibytes (i.e. blocks of 1024 bytes).
<span class="since">Since 1.2.11</span> one can use an additional <a
href="#elementsMemoryAllocation"><code>unit</code></a> attribute to
@@ -5734,11 +5785,11 @@
<p>
Provides a bridge from the VM directly to the LAN. This assumes
there is a bridge device on the host which has one or more of the hosts
physical NICs enslaved. The guest VM will have an associated tun device
physical NICs attached. The guest VM will have an associated tun device
created with a name of vnetN, which can also be overridden with the
&lt;target&gt; element (see
<a href="#elementsNICSTargetOverride">overriding the target element</a>).
The tun device will be enslaved to the bridge. The IP range / network
The tun device will be attached to the bridge. The IP range / network
configuration is whatever is used on the LAN. This provides the guest VM
full incoming &amp; outgoing net access just like a physical machine.
</p>
@@ -8798,6 +8849,18 @@ qemu-kvm -net nic,model=? /dev/null
backend device is a TPM 2.0. <span class="since">Since 6.1.0</span>,
pSeries guests on PPC64 are supported and the default is
<code>tpm-spapr</code>.

<span class="since">Since 6.5.0</span>, a new model called
<code>spapr-tpm-proxy</code> was added for pSeries guests. This model
only works with the <code>passthrough</code> backend. It creates a
TPM Proxy device that communicates with an existing TPM Resource Manager
in the host, for example <code>/dev/tpmrm0</code>, enabling the guest to
run in secure virtual machine mode with the help of an Ultravisor. Adding
a TPM Proxy to a pSeries guest brings no security benefits unless the guest
is running on a PPC64 host that has an Ultravisor and a TPM Resource Manager.
Only one TPM Proxy device is allowed per guest, but a TPM Proxy device can
be added together with
other TPM devices.
</p>
</dd>
<dt><code>backend</code></dt>
@@ -8810,7 +8873,7 @@ qemu-kvm -net nic,model=? /dev/null
<dt><code>passthrough</code></dt>
<dd>
<p>
Use the host's TPM device.
Use the host's TPM or TPM Resource Manager device.
</p>
<p>
This backend type requires exclusive access to a TPM device on
@@ -8818,6 +8881,11 @@ qemu-kvm -net nic,model=? /dev/null
qualified file name is specified by path attribute of the
<code>source</code> element. If no file name is specified then
/dev/tpm0 is automatically used.

<span class="since">Since 6.5.0</span>, when choosing the
<code>spapr-tpm-proxy</code> model, the file name specified is
expected to be a TPM Resource Manager device, e.g.
<code>/dev/tpmrm0</code>.
</p>
</dd>
</dl>
@@ -9326,6 +9394,15 @@ qemu-kvm -net nic,model=? /dev/null
<span class="since">Since 3.5.0</span> (QEMU/KVM only)
</p>
</dd>
<dt><code>aw_bits</code></dt>
<dd>
<p>
The <code>aw_bits</code> attribute can be used to set
the address width to allow mapping larger iova addresses
in the guest.
<span class="since">Since 6.5.0</span> (QEMU/KVM only)
</p>
</dd>
</dl>
</dd>
</dl>


+ 11
- 2
docs/formatdomaincaps.html.in View File

@@ -201,7 +201,12 @@
&lt;domainCapabilities&gt;
...
&lt;cpu&gt;
&lt;mode name='host-passthrough' supported='yes'/&gt;
&lt;mode name='host-passthrough' supported='yes'&gt;
&lt;enum name='hostPassthroughMigratable'&gt;
&lt;value&gt;on&lt;/value&gt;
&lt;value&gt;off&lt;/value&gt;
&lt;/enum&gt;
&lt;/mode&gt;
&lt;mode name='host-model' supported='yes'&gt;
&lt;model fallback='allow'&gt;Broadwell&lt;/model&gt;
&lt;vendor&gt;Intel&lt;/vendor&gt;
@@ -227,7 +232,11 @@

<dl>
<dt><code>host-passthrough</code></dt>
<dd>No mode specific details are provided.</dd>
<dd>
The <code>hostPassthroughMigratable</code> enum shows possible values
of the <code>migratable</code> attribute for the &lt;cpu&gt; element
with <code>mode='host-passthrough'</code> in the domain XML.
</dd>

<dt><code>host-model</code></dt>
<dd>


+ 14
- 0
docs/formatnetwork.html.in View File

@@ -276,6 +276,20 @@
&lt;/nat&gt;
&lt;/forward&gt;
...</pre>

<p>
<span class="since">Since 6.5.0</span> it is possible to
enable NAT with IPv6 networking. As noted above, IPv6
has historically done plain forwarding and thus to avoid
breaking historical compatibility, IPv6 NAT must be
explicitly requested.
</p>
<pre>
...
&lt;forward mode='nat'&gt;
&lt;nat ipv6='yes'/&gt;
&lt;/forward&gt;
...</pre>
</dd>

<dt><code>route</code></dt>


+ 17
- 4
docs/formatnode.html.in View File

@@ -31,11 +31,16 @@
name is just the bus type and address, as in
"pci_0000_00_02_1" or "usb_1_5_3", but some devices are able
to provide more specific names, such as
"net_eth1_00_27_13_6a_fe_00".
"net_eth1_00_27_13_6a_fe_00". This is a read-only field that is
reported by the device driver. If this element is set when defining a
new device, it will be ignored.

</dd>
<dt><code>path</code></dt>
<dd>
Fully qualified sysfs path to the device.
Fully qualified sysfs path to the device. This is a read-only field
that is reported by the device driver. If this element is set when
defining a new device, it will be ignored.
</dd>
<dt><code>parent</code></dt>
<dd>
@@ -390,8 +395,16 @@
<dt><code>iommuGroup</code></dt>
<dd>
This element supports a single attribute <code>number</code>
which holds the IOMMU group number the mediated device belongs
to.
which holds the IOMMU group number to which the mediated device
belongs. This is a read-only field that is reported by the
device driver.
</dd>
<dt><code>attr</code></dt>
<dd>
This optional element can occur multiple times. It represents a
vendor-specific attribute that is used to configure this
mediated device. It has two required attributes:
<code>name</code> and <code>value</code>.
</dd>
</dl>
</dd>


+ 7
- 7
docs/hacking.rst View File

@@ -9,15 +9,15 @@ Repositories and external resources
===================================

The official upstream repository is kept in git
(``https://libvirt.org/git/libvirt.git``) and is browsable
(``https://gitlab.com/libvirt/libvirt``) and is browsable
along with other libvirt-related repositories (e.g.
libvirt-python) `online <https://libvirt.org/git/>`__.
libvirt-python) `online <https://gitlab.com/libvirt>`__.

Patches to translations are maintained via the `zanata
project <https://fedora.zanata.org/>`__. If you want to fix a
translation in a .po file, join the appropriate language team.
The libvirt release process automatically pulls the latest
version of each translation file from zanata.
Patches to translations are maintained via the `Fedora Weblate
service <https://translate.fedoraproject.org/projects/libvirt/libvirt>`__.
If you want to contirbute to translations of libvirt, join the appropriate
language team in Weblate. Translation updates to libvirt will be merged
during the feature freeze window.

Preparing patches
=================


+ 27
- 0
docs/hooks.html.in View File

@@ -36,6 +36,9 @@
<li>If your installation of libvirt has instead been compiled from
source, it is likely to be
<code>/usr/local/etc/libvirt/hooks/</code>.</li>
<li><span class="since">Since 6.5.0</span>, you can also place several
hook scripts in the directories
<code>/etc/libvirt/hooks/&lt;driver&gt;.d/</code>.</li>
</ul>
<p>To use hook scripts, you will need to create this <code>hooks</code>
directory manually, place the desired hook scripts inside, then make
@@ -59,6 +62,10 @@
Executed when a network is started or stopped or an
interface is plugged/unplugged to/from the network</li>
</ul>
<p><span class="since">Since 6.5.0</span>, you can also have
several scripts with any name in the directories
<code>/etc/libvirt/hooks/&lt;driver&gt;.d/</code>. They are
executed in alphabetical order after main script.</p>
<br/>

<h2><a id="structure">Script structure</a></h2>
@@ -191,6 +198,16 @@
script returns failure or the output XML is not valid, restore of the
image will be aborted. This hook may be used, e.g., to change
location of disk images for restored domains.</li>
<li><span class="since">Since 6.5.0</span>, you can also place several
hook scripts in the directory
<code>/etc/libvirt/hooks/qemu.d/</code>. They are executed in
alphabetical order after main script. In this case each script also
acts as filter and can modify the domain XML and print it out on
its standart output. This script output is passed to standard input
next script in order. Empty output from any script is also identical
to copying the input XML without changing it.
In case any script returns failure common process will be aborted,
but all scripts from the directory will are executed.</li>
<li><span class="since">Since 0.9.13</span>, the qemu hook script
is also called when the libvirtd daemon restarts and reconnects
to previously running QEMU processes. If the script fails, the
@@ -274,6 +291,16 @@
script returns failure or the output XML is not valid, incoming
migration will be canceled. This hook may be used, e.g., to change
location of disk images for incoming domains.</li>
<li><span class="since">Since 6.5.0</span>, you can also place several
hook scripts in the directory
<code>/etc/libvirt/hooks/libxl.d/</code>. They are executed in
alphabetical order after main script. In this case each script also
acts as filter and can modify the domain XML and print it out on
its standart output. This script output is passed to standard input
next script in order. Empty output from any script is also identical
to copying the input XML without changing it.
In case any script returns failure common process will be aborted,
but all scripts from the directory will are executed.</li>
<li><span class="since">Since 2.1.0</span>, the libxl hook script
is also called when the libvirtd daemon restarts and reconnects
to previously running Xen domains. If the script fails, the


+ 5
- 4
docs/internals/rpc.html.in View File

@@ -447,7 +447,8 @@ C &lt;-- |32| 8 | 1 | 3 | 1 | 1 | 0 | .o.oOo | &lt;-- S (reply)
<dt><code>virNetSASLContextPtr</code> (virnetsaslcontext.h)</dt>
<dd>The virNetSASLContext APIs maintain SASL state for a network
service (server or client). This is primarily used on the server
to provide a whitelist of allowed SASL usernames for clients.
to provide an access control list of SASL usernames permitted as
clients.
</dd>

<dt><code>virNetSASLSessionPtr</code> (virnetsaslcontext.h)</dt>
@@ -460,7 +461,7 @@ C &lt;-- |32| 8 | 1 | 3 | 1 | 1 | 0 | .o.oOo | &lt;-- S (reply)
<dt><code>virNetTLSContextPtr</code> (virnettlscontext.h)</dt>
<dd>The virNetTLSContext APIs maintain TLS state for a network
service (server or client). This is primarily used on the server
to provide a whitelist of allowed x509 distinguished names, as
to provide an access control list of x509 distinguished names, as
well as diffie-hellman keys. It can also do validation of
x509 certificates prior to initiating a connection, in order
to improve detection of configuration errors.
@@ -760,8 +761,8 @@ C &lt;-- |32| 8 | 1 | 3 | 1 | 1 | 0 | .o.oOo | &lt;-- S (reply)
next step is to decode the RPC header. The header is validated to
ensure the request is sensible, ie the server should not receive a
method reply from a client. If the client has not yet authenticated,
a security check is also applied to make sure the procedure is on the
whitelist of those allowed prior to auth. If the packet is a method
an access control list check is also performed to make sure the procedure
is one of those allowed prior to auth. If the packet is a method
call, it will be placed on a global processing queue. The event loop
thread is now done with the packet for the time being.
</p>


+ 2
- 10
docs/java.html.in View File

@@ -26,19 +26,11 @@ which you can use to include this in your maven projects.</p>
<h2>GIT source repository</h2>
<p> The Java bindings code source is now maintained in a <a
href="http://git-scm.com/">git</a> repository available on
<a href="https://libvirt.org/git/">libvirt.org</a>:
<a href="https://gitlab.com/libvirt/libvirt-java/">gitlab.com</a>:
</p>
<pre>
git clone https://libvirt.org/git/libvirt-java.git
git clone https://gitlab.com/libvirt/libvirt-java.git
</pre>
<p>
It can also be browsed at
</p>
<pre>

<a href="https://libvirt.org/git/?p=libvirt-java.git;a=summary">https://libvirt.org/git/?p=libvirt-java.git;a=summary</a>
</pre>


<h2>Building</h2>
<p>The code is built using ant, and assumes that you have the jna jar installed. Once you have downloaded


+ 9
- 0
docs/kbase.html.in View File

@@ -14,6 +14,9 @@
<dt><a href="kbase/secureusage.html">Secure usage</a></dt>
<dd>Secure usage of the libvirt APIs</dd>

<dt><a href="kbase/s390_protected_virt.html">Protected virtualization on s390</a></dt>
<dd>Running secure s390 guests with IBM Secure Execution</dd>

<dt><a href="kbase/launch_security_sev.html">Launch security</a></dt>
<dd>Securely launching VMs with AMD SEV</dd>

@@ -36,6 +39,12 @@

<dt><a href="kbase/virtiofs.html">Virtio-FS</a></dt>
<dd>Share a filesystem between the guest and the host</dd>

<dt><a href="kbase/kvm-realtime.html">KVM real time</a></dt>
<dd>Run real time workloads in guests on a KVM hypervisor</dd>

<dt><a href="kbase/incrementalbackupinternals.html">Incremental backup internals</a></dt>
<dd>Incremental backup implementation details relevant for users</dd>
</dl>
</div>



+ 1
- 1
docs/kbase/backing_chains.rst View File

@@ -120,7 +120,7 @@ means that the **-F** parameter of ``qemu-img`` must always be used.

::

qemu-img -f qcow2 -F qcow2 -b $BACKING_IMAGE_PATH $IMAGE_PATH
qemu-img create -f qcow2 -F qcow2 -b $BACKING_IMAGE_PATH $IMAGE_PATH

Note that if ``$BACKING_IMAGE_PATH`` is relative the path is considered relative to
the location of ``$IMAGE_PATH``.


+ 284
- 0
docs/kbase/incrementalbackupinternals.rst View File

@@ -0,0 +1,284 @@
================================================
Internals of incremental backup handling in qemu
================================================

.. contents::

Libvirt's implementation of incremental backups in the ``qemu`` driver uses
qemu's ``block-dirty-bitmaps`` under the hood to track the guest visible disk
state changes corresponding to the points in time described by a libvirt
checkpoint.

There are some semantica implications with how libvirt creates and manages the
bitmaps which de-facto become API as they are written into the disk images, and
this document will try to summarize them.

Glossary
========

See the knowledge base article on
`domain state capture <https://libvirt.org/kbase/domainstatecapture.html>`_ for
a deeper explanation of some of the concepts.

Checkpoint

A libvirt object which represents a named point in time of the life of the
vm where libvirt tracks writes the VM has done, thereby allowing a backup of
only the blocks which changed. Note that state of the VM memory is _not_
captured.

A checkpoint can be created either explicitly via the corresponding API
(although this isn't very useful on its own), or simultaneously with an
incremental or full backup of the VM using the ``virDomainBackupBegin`` API
which allows a next backup to only copy the differences.

Backup

A copy of either all blocks of selected disks (full backup) or blocks changed
since a checkpoint (incremental backup) at the time the backup job was
started. (Blocks modified while the backup job is running are not part of the
backup!)

Snapshot

Similarly to a checkpoint it's a point in time in the lifecycle of the VM
but the state of the VM including memory is captured at that point allowing
returning to the state later.

Blockjob

A long running job which modifies the shape and/or location of the disk
backing chain (images storing the disk contents). Libvirt supports
``block pull`` where data is moved up the chain towards the active layer,
``block commit`` where data is moved down the chain towards the base/oldest
image. These blockjobs always remove images from the backing chain. Lastly
``block copy`` where image is moved to a different location (and possibly
collapsed moving all of the data into the new location into the one image).

block-dirty-bitmap (bitmap)

A data structure in qemu tracking which blocks were written by the guest
OS since the bitmap was created.

Relationships of bitmaps, checkpoints and VM disks
==================================================

When a checkpoint is created libvirt creates a block-dirty-bitmap for every
configured VM disk named the same way as the chcheckpoint. The bitmap is
actively recording which blocks were changed by the guest OS from that point on.
Other bitmaps are not impacted by any way as they are self-contained:

::

+----------------+ +----------------+
| disk: vda | | disk: vdb |
+--------+-------+ +--------+-------+
| |
+--------v-------+ +--------v-------+
| vda-1.qcow2 | | vdb-1.qcow2 |
| | | |
| bitmaps: chk-a | | bitmaps: chk-a |
| chk-b | | chk-b |
| | | |
+----------------+ +----------------+

Bitmaps are created at the same time to track changes to all disks in sync and
are active and persisted in the QCOW2 image. Other formats currently don't
support this feature.

Modification of bitmaps outside of libvirt is not recommended, but when adhering
to the same semantics which the document will describe it should be safe to do
so, even if we obviously can't guarantee that.


Integration with external snapshots
===================================

External snapshot terminology
-----------------------------

External snapshots on a disk level consist of layered chains of disk images. An
image in the chain can have a ``backing image`` placed below. Any chunk in the
current image which was not written explicitly is transparent and if read the
data from the backing image is passed through. An image placed on top of the
current image is called ``overlay``.

The bottommost backing image at the end of the chain is also usually described
as ``base image``.

The topmost overlay is the image which is being written to by the VM and is also
described as the ``active`` layer or image.

Handling of bitmaps during snapshots
------------------------------------

Creating an external snapshot involves adding a overlay on top of the previously
active image. Libvirt requires that all ``block-dirty-bitmaps`` which correspond
to the checkpoint must be created in the new overlay before any write from the
guest reaches the overlay to continue tracking which blocks are dirtied.

Since there are no new bitmaps created by ``qemu`` or ``qemu-img`` by default
when creating an overlay, we need to re-create the appropriate bitmaps
(see below) in the new overlay based on the previously active bitmaps in the
active image. The new bitmaps are created with the same granularity.

After taking a snapshot of the ``vda`` disk from the example above placed into
``vda-2.qcow2`` the following topology will be created:

::

+----------------+
| disk: vda |
+-------+--------+
|
+-------v--------+ +----------------+
| vda-2.qcow2 | | vda-1.qcow2 |
| | | |
| bitmaps: chk-a +----> bitmaps: chk-a |
| chk-b | | chk-b |
| | | |
+----------------+ +----------------+

Manipulating bitmaps in shell
-----------------------------

**NOTE:** Any of the examples expect that the full image chain isn't used by any
running VM at the time.

``qemu-img info`` command reports information about dirty bitmaps in an image:

::

$ qemu-img info -f qcow2 vda-1.qcow2
image: vda-1.qcow2
file format: qcow2
virtual size: 100 MiB (104857600 bytes)
disk size: 220 KiB
cluster_size: 65536
Format specific information:
compat: 1.1
compression type: zlib
lazy refcounts: false
bitmaps:
[0]:
flags:
[0]: in-use
[1]: auto
name: chk-a
granularity: 65536
[1]:
flags:
[0]: auto
name: chk-b
granularity: 65536
refcount bits: 16
corrupt: false

The ``flags`` have following meanings:

``auto`` - **recording**

The bitmap is automatically activated when the image is opened for writing
and thus it's actively recording writes.

``in-use`` - **inconsistent**

The bitmap was not properly saved when the qemu process was shut down last
time thus didn't consistently record all the changed sectors.

It's recommended to use ``--output=json`` parameter to work with a machine
readable output rather than trying to process the human readable output by
scripts. For processing JSON in shell the ``jq`` tool can be used.

The ``qemu-img bitmap`` command allows modification of block-dirty-bitmaps of an
offline image. It supports the following operations relevant to this document
(see man page for full list of operations):

``--add NAME``
Creates a new bitmap named ``NAME``. Optionally ``-g`` can be used to
specify granularity.

``--remove NAME``
Deletes bitmap ``NAME``.

``--merge SRCBITMAP -b SRCFILE -F SRCFILEFMT DSTBITMAP``
Merges bitmap ``SRCBITMAP`` from ``SRCFILE`` into ``DSTBITMAP``.

Checking bitmap health
----------------------

QEMU optimizes disk writes by only updating the bitmaps in certain cases. This
also can cause problems in cases when e.g. QEMU crashes.

For a chain of corresponding bitmaps in a backing chain images to be considered
valid and eligible for use for an incremental backup with
``virDomainBackupBegin`` the bitmaps intended to be used must conform to the
following rules:

1) active/topmost image must contain the bitmap
2) if a bitmap with the same name is contained in one of the backing images it
must be a contiguous subchain starting from the topmost image which contains
the bitmaps (no gaps)
3) all of the above bitmaps must be marked as **recording**
4) all of the above bitmaps must not be **inconsistent**

(See also the ``qemuBlockBitmapChainIsValid`` helper method in
``src/qemu/qemu_block.c``)

Creating external snapshots manually
--------------------------------------

To create the same topology outside of libvirt (e.g when doing snapshots