[PATCH 0/8] docs: Convert some pages to rST and clean up (part 2)
Jano asked me to expedite the conversion of the 'downloads' page so he can do some modifications. Peter Krempa (8): docs: Convert 'downloads' page to rST https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/down... docs: Convert 'contact' page to rST https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/cont... docs: Convert 'testapi' page to rST https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/test... syntax-check: Don't check for non-reentrant functions in '.rst' files docs: Convert 'nss' page to rST https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/nss.... docs: Convert 'pci-hotplug' page to rST https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/pci-... docs: Convert 'testtck' page to rST https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/test... docs: Convert 'testsuites' page to rST https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/test... build-aux/syntax-check.mk | 2 +- docs/contact.html.in | 116 ------- docs/contact.rst | 94 ++++++ docs/downloads.html.in | 661 -------------------------------------- docs/downloads.rst | 417 ++++++++++++++++++++++++ docs/meson.build | 14 +- docs/nss.html.in | 189 ----------- docs/nss.rst | 154 +++++++++ docs/pci-hotplug.html.in | 185 ----------- docs/pci-hotplug.rst | 146 +++++++++ docs/testapi.html.in | 35 -- docs/testapi.rst | 34 ++ docs/testsuites.html.in | 41 --- docs/testsuites.rst | 37 +++ docs/testtck.html.in | 40 --- docs/testtck.rst | 37 +++ 16 files changed, 927 insertions(+), 1275 deletions(-) delete mode 100644 docs/contact.html.in create mode 100644 docs/contact.rst delete mode 100644 docs/downloads.html.in create mode 100644 docs/downloads.rst delete mode 100644 docs/nss.html.in create mode 100644 docs/nss.rst delete mode 100644 docs/pci-hotplug.html.in create mode 100644 docs/pci-hotplug.rst delete mode 100644 docs/testapi.html.in create mode 100644 docs/testapi.rst delete mode 100644 docs/testsuites.html.in create mode 100644 docs/testsuites.rst delete mode 100644 docs/testtck.html.in create mode 100644 docs/testtck.rst -- 2.35.1
The table was manually converted to a set of 'list-table'-s for better experience of viewing the text. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/downloads.html.in | 661 ----------------------------------------- docs/downloads.rst | 417 ++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 418 insertions(+), 662 deletions(-) delete mode 100644 docs/downloads.html.in create mode 100644 docs/downloads.rst diff --git a/docs/downloads.html.in b/docs/downloads.html.in deleted file mode 100644 index 40724cce22..0000000000 --- a/docs/downloads.html.in +++ /dev/null @@ -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 <jdenemar@redhat.com> -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) <veillard@redhat.com> -uid [ unknown] Daniel Veillard <Daniel.Veillard@w3.org> - </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 <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----- - </pre> - - </body> -</html> diff --git a/docs/downloads.rst b/docs/downloads.rst new file mode 100644 index 0000000000..3920ecb604 --- /dev/null +++ b/docs/downloads.rst @@ -0,0 +1,417 @@ +========= +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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-csharp.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-go-module.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-java.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-ocaml.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-perl.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-php.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-python.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-ruby.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-rust.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-glib.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-go-xml-module.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-dbus.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-console-proxy.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-cim.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libcmpiutil.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-snmp.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-sandbox.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-tck.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-test-API.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-ci.git;a=summary>`__ + `github <https://github.com/libvirt/libvirt-ci>`__ + + * - CIM Test + - + - `gitlab <https://gitlab.com/libvirt/cimtest>`__ + - `issues <https://gitlab.com/libvirt/cimtest/-/issues>`__ + - `libvirt <https://libvirt.org/git/?p=cimtest.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-publican.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-appdev-guide.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-appdev-guide-python.git;a=summary>`__ + `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>`__ + - `libvirt <https://libvirt.org/git/?p=libvirt-virshcmdref.git;a=summary>`__ + `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 `project GIT server <https://libvirt.org/git/>`__. Each module +can be cloned anonymously using: + +:: + + git clone https://libvirt.org/git/[module name].git + +The ``git://`` protocol is also available if desired, but ``https://`` is +encouraged, since it is more reliable when faced with strict firewalls. + +:: + + git clone git://libvirt.org/[module name].git + +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 +`libvir-list <contact.html>`__ mailing list. Also note that some repositories +listed below allow HTTP checkouts too. + +:: + + https://github.com/libvirt/ + https://gitlab.com/libvirt/ + +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----- diff --git a/docs/meson.build b/docs/meson.build index 7146bd078b..c1d4072cf7 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -24,7 +24,6 @@ docs_html_in_files = [ 'csharp', 'dbus', 'docs', - 'downloads', 'drvbhyve', 'drvesx', 'drvhyperv', @@ -85,6 +84,7 @@ docs_rst_files = [ 'contribute', 'daemons', 'developer-tooling', + 'downloads', 'drivers', 'drvch', 'drvqemu', -- 2.35.1
On a Thursday in 2022, Peter Krempa wrote:
The table was manually converted to a set of 'list-table'-s for better experience of viewing the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/downloads.html.in | 661 ----------------------------------------- docs/downloads.rst | 417 ++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 418 insertions(+), 662 deletions(-) delete mode 100644 docs/downloads.html.in create mode 100644 docs/downloads.rst
diff --git a/docs/downloads.html.in b/docs/downloads.html.in deleted file mode 100644 index 40724cce22..0000000000 --- a/docs/downloads.html.in +++ /dev/null @@ -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 <jdenemar@redhat.com> -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) <veillard@redhat.com> -uid [ unknown] Daniel Veillard <Daniel.Veillard@w3.org> - </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 <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----- - </pre> - - </body> -</html> diff --git a/docs/downloads.rst b/docs/downloads.rst new file mode 100644 index 0000000000..3920ecb604 --- /dev/null +++ b/docs/downloads.rst @@ -0,0 +1,417 @@ +========= +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>`__
Missing equivalent of:
- <a href="https://libvirt.org/git/?p=libvirt.git;a=summary">libvirt</a> before the github link.
If you don't put it there, I won't be able to remove it in a followup patch.
+ - `api ref <html/index.html>`__ + `changes <news.html>`__ +
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
On Thu, Mar 10, 2022 at 17:07:54 +0100, Ján Tomko wrote:
On a Thursday in 2022, Peter Krempa wrote:
The table was manually converted to a set of 'list-table'-s for better experience of viewing the text.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/downloads.html.in | 661 ----------------------------------------- docs/downloads.rst | 417 ++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 418 insertions(+), 662 deletions(-) delete mode 100644 docs/downloads.html.in create mode 100644 docs/downloads.rst
[...]
+ +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>`__
Missing equivalent of:
- <a href="https://libvirt.org/git/?p=libvirt.git;a=summary">libvirt</a> before the github link.
Oops, this first set was converted manually before I considered it too tedious :D
If you don't put it there, I won't be able to remove it in a followup patch.
+ - `api ref <html/index.html>`__ + `changes <news.html>`__ +
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Jano
Preserve the 'irc' and 'email' anchors. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/contact.html.in | 116 ------------------------------------------- docs/contact.rst | 94 +++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 95 insertions(+), 117 deletions(-) delete mode 100644 docs/contact.html.in create mode 100644 docs/contact.rst diff --git a/docs/contact.html.in b/docs/contact.html.in deleted file mode 100644 index ad95800b1b..0000000000 --- a/docs/contact.html.in +++ /dev/null @@ -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> diff --git a/docs/contact.rst b/docs/contact.rst new file mode 100644 index 0000000000..75b1239301 --- /dev/null +++ b/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. diff --git a/docs/meson.build b/docs/meson.build index c1d4072cf7..aaafa7d8e1 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -20,7 +20,6 @@ docs_assets = [ docs_html_in_files = [ '404', 'cgroups', - 'contact', 'csharp', 'dbus', 'docs', @@ -81,6 +80,7 @@ docs_rst_files = [ 'coding-style', 'committer-guidelines', 'compiling', + 'contact', 'contribute', 'daemons', 'developer-tooling', -- 2.35.1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/testapi.html.in | 35 ----------------------------------- docs/testapi.rst | 34 ++++++++++++++++++++++++++++++++++ 3 files changed, 35 insertions(+), 36 deletions(-) delete mode 100644 docs/testapi.html.in create mode 100644 docs/testapi.rst diff --git a/docs/meson.build b/docs/meson.build index aaafa7d8e1..087afb15d9 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -57,7 +57,6 @@ docs_html_in_files = [ 'python', 'remote', 'storage', - 'testapi', 'testsuites', 'testtck', 'tlscerts', @@ -112,6 +111,7 @@ docs_rst_files = [ 'styleguide', 'submitting-patches', 'support', + 'testapi', ] # list of web targets to build for docs/web rule diff --git a/docs/testapi.html.in b/docs/testapi.html.in deleted file mode 100644 index e7cd9453ee..0000000000 --- a/docs/testapi.html.in +++ /dev/null @@ -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> diff --git a/docs/testapi.rst b/docs/testapi.rst new file mode 100644 index 0000000000..9aa0afb761 --- /dev/null +++ b/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. -- 2.35.1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- build-aux/syntax-check.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build-aux/syntax-check.mk b/build-aux/syntax-check.mk index a8c9153b20..d1db1d0267 100644 --- a/build-aux/syntax-check.mk +++ b/build-aux/syntax-check.mk @@ -1620,7 +1620,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$$ -- 2.35.1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/nss.html.in | 189 ----------------------------------------------- docs/nss.rst | 154 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 155 insertions(+), 190 deletions(-) delete mode 100644 docs/nss.html.in create mode 100644 docs/nss.rst diff --git a/docs/meson.build b/docs/meson.build index 087afb15d9..3bdea1407d 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -51,7 +51,6 @@ docs_html_in_files = [ 'internals', 'java', 'logging', - 'nss', 'pci-hotplug', 'php', 'python', @@ -103,6 +102,7 @@ docs_rst_files = [ 'macos', 'migration', 'newreposetup', + 'nss', 'pci-addresses', 'platforms', 'programming-languages', diff --git a/docs/nss.html.in b/docs/nss.html.in deleted file mode 100644 index 5c58d1bd49..0000000000 --- a/docs/nss.html.in +++ /dev/null @@ -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> diff --git a/docs/nss.rst b/docs/nss.rst new file mode 100644 index 0000000000..8f98330221 --- /dev/null +++ b/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. -- 2.35.1
One internal reference was modified to work properly. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/pci-hotplug.html.in | 185 --------------------------------------- docs/pci-hotplug.rst | 146 ++++++++++++++++++++++++++++++ 3 files changed, 147 insertions(+), 186 deletions(-) delete mode 100644 docs/pci-hotplug.html.in create mode 100644 docs/pci-hotplug.rst diff --git a/docs/meson.build b/docs/meson.build index 3bdea1407d..cdf78a04b4 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -51,7 +51,6 @@ docs_html_in_files = [ 'internals', 'java', 'logging', - 'pci-hotplug', 'php', 'python', 'remote', @@ -104,6 +103,7 @@ docs_rst_files = [ 'newreposetup', 'nss', 'pci-addresses', + 'pci-hotplug', 'platforms', 'programming-languages', 'securityprocess', diff --git a/docs/pci-hotplug.html.in b/docs/pci-hotplug.html.in deleted file mode 100644 index d61af1930e..0000000000 --- a/docs/pci-hotplug.html.in +++ /dev/null @@ -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> -<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></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> -<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'/></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> -<controller type='pci' model='pcie-to-pci-bridge'/></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> -<controller type='pci' index='0' model='pci-root'/></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> -<controller type='pci' index='0' model='pci-root'> - <model name='spapr-pci-host-bridge'/> - <target index='0'/> -</controller></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> -<controller type='pci' model='pci-root'/> -<controller type='pci' model='pci-root'/> -<controller type='pci' model='pci-root'/></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> diff --git a/docs/pci-hotplug.rst b/docs/pci-hotplug.rst new file mode 100644 index 0000000000..bc7fdbbd86 --- /dev/null +++ b/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``. -- 2.35.1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/testtck.html.in | 40 ---------------------------------------- docs/testtck.rst | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 38 insertions(+), 41 deletions(-) delete mode 100644 docs/testtck.html.in create mode 100644 docs/testtck.rst diff --git a/docs/meson.build b/docs/meson.build index cdf78a04b4..d6b944a156 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -56,7 +56,6 @@ docs_html_in_files = [ 'remote', 'storage', 'testsuites', - 'testtck', 'tlscerts', 'uri', 'windows', @@ -112,6 +111,7 @@ docs_rst_files = [ 'submitting-patches', 'support', 'testapi', + 'testtck', ] # list of web targets to build for docs/web rule diff --git a/docs/testtck.html.in b/docs/testtck.html.in deleted file mode 100644 index 137586682b..0000000000 --- a/docs/testtck.html.in +++ /dev/null @@ -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> diff --git a/docs/testtck.rst b/docs/testtck.rst new file mode 100644 index 0000000000..51de095657 --- /dev/null +++ b/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. -- 2.35.1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/testsuites.html.in | 41 ----------------------------------------- docs/testsuites.rst | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 38 insertions(+), 42 deletions(-) delete mode 100644 docs/testsuites.html.in create mode 100644 docs/testsuites.rst diff --git a/docs/meson.build b/docs/meson.build index d6b944a156..868267b764 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -55,7 +55,6 @@ docs_html_in_files = [ 'python', 'remote', 'storage', - 'testsuites', 'tlscerts', 'uri', 'windows', @@ -111,6 +110,7 @@ docs_rst_files = [ 'submitting-patches', 'support', 'testapi', + 'testsuites', 'testtck', ] diff --git a/docs/testsuites.html.in b/docs/testsuites.html.in deleted file mode 100644 index 2e61684b63..0000000000 --- a/docs/testsuites.html.in +++ /dev/null @@ -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> diff --git a/docs/testsuites.rst b/docs/testsuites.rst new file mode 100644 index 0000000000..4fc733e615 --- /dev/null +++ b/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/>`__. -- 2.35.1
On a Thursday in 2022, Peter Krempa wrote:
Jano asked me to expedite the conversion of the 'downloads' page so he can do some modifications.
Peter Krempa (8): docs: Convert 'downloads' page to rST
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/down...
docs: Convert 'contact' page to rST
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/cont...
docs: Convert 'testapi' page to rST
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/test...
syntax-check: Don't check for non-reentrant functions in '.rst' files docs: Convert 'nss' page to rST
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/nss....
docs: Convert 'pci-hotplug' page to rST
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/pci-...
docs: Convert 'testtck' page to rST
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/test...
docs: Convert 'testsuites' page to rST
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/2188545131/artifacts/website/test...
build-aux/syntax-check.mk | 2 +- docs/contact.html.in | 116 ------- docs/contact.rst | 94 ++++++ docs/downloads.html.in | 661 -------------------------------------- docs/downloads.rst | 417 ++++++++++++++++++++++++ docs/meson.build | 14 +- docs/nss.html.in | 189 ----------- docs/nss.rst | 154 +++++++++ docs/pci-hotplug.html.in | 185 ----------- docs/pci-hotplug.rst | 146 +++++++++ docs/testapi.html.in | 35 -- docs/testapi.rst | 34 ++ docs/testsuites.html.in | 41 --- docs/testsuites.rst | 37 +++ docs/testtck.html.in | 40 --- docs/testtck.rst | 37 +++ 16 files changed, 927 insertions(+), 1275 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (2)
-
Ján Tomko -
Peter Krempa