From nobody Wed May 15 09:11:24 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1646927535; cv=none; d=zohomail.com; s=zohoarc; b=caXs38dbVrQ8sHXMK3DuRJuIzDXcRNDfWQABWJ4Nh932Bmjgefyq/dz3pfapMXaTSJc0EP8g77HCxHWc4qstKp25v7EWEukmgmEtYjaeUn8yINVk9jRE1E3Df2lMCKRBL+2gdSVi4x7KE8tD6tM4hdwvya13S4a2FLFX4BAhT0w= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927535; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=561PUgR8pNCZ/BpH4YNRCdIAJrIGYO8uuO7233ZHvsU=; b=WIC0Id46HbjJAUZyXCjPUQVAOeL9X0n4XCuY1ym+BcwUhbRk+xGi3wQpcJCvuqU0p6/oCee+b0cq5MGbLxvhRTcKyegjxD68gBQtWxoy6wsBWO/roPM24o1oRt0ntVXH3uKfb6ASQaNUrJwQcDTWHev/xcMAM/iG3iEkpi3a2cw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1646927535066540.6175615853884; Thu, 10 Mar 2022 07:52:15 -0800 (PST) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-563-OZ9iBVitOUClfW5HMdRC9Q-1; Thu, 10 Mar 2022 10:51:47 -0500 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 3955B3800519; Thu, 10 Mar 2022 15:51:44 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 21244463EB3; Thu, 10 Mar 2022 15:51:44 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id EF707195357C; Thu, 10 Mar 2022 15:51:43 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id ADB14195FD6C for ; Thu, 10 Mar 2022 15:51:42 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 5A49B7C029; Thu, 10 Mar 2022 15:51:42 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 38F987C02A for ; Thu, 10 Mar 2022 15:51:40 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927533; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=561PUgR8pNCZ/BpH4YNRCdIAJrIGYO8uuO7233ZHvsU=; b=YGfEU17OAilAcfk3kjeIepuHjgF63Ij0LRud5fVt7QyaKoL2nUgqtlv13Pgw+vADfs2aMH jaxS7jHeHw3gXXXnj3zl0LLu3lJagb94psTfiLZ6NcXGJLdKKTlq9uxY5OOHseM4Zqg3DQ n1sM7ywIpQ44ycZ+3DSH99MMlDL+ZS0= X-MC-Unique: OZ9iBVitOUClfW5HMdRC9Q-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 1/8] docs: Convert 'downloads' page to rST Date: Thu, 10 Mar 2022 16:51:23 +0100 Message-Id: <15e028ea101b2658ea5a606b2f2a6b8eac75d0a7.1646927156.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.10 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1646927536044100001 The table was manually converted to a set of 'list-table'-s for better experience of viewing the text. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- 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 @@ - - - - -

Downloads

- -
    - -

    Project modules

    - -

    - The libvirt project maintains a number of inter-related modules beyo= nd - the core C library/daemon. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ModuleReleasesGIT RepoBug TrackerGIT MirrorsResources
    libvirt - libvirt - - gitlab - - issues= - - libvirt - github - - api ref - changes -
    Language bindings
    C# - libvirt - - gitlab - - issues - - libvirt - github -
    Go - libvirt - - gitla= b - - issues - - libvirt - githu= b - - api ref<= /a> -
    Java - libvirt - - gitlab - - i= ssues - - libvirt - github -
    OCaml - libvirt - - gitlab - - = issues - - libvirt - github -
    Perl (Sys::Virt) - cpan - - gitlab - - i= ssues - - libvirt - github - - api ref - changes -
    PHP - libvirt - - gitlab - - is= sues - - libvirt - github -
    Python - libvirt - pypi - - gitlab - - issues - - libvirt - github -
    Ruby - libvirt - - gitlab - - i= ssues - - libvirt - github -
    Rust - crates.io - - gitlab - - i= ssues - - libvirt - github - - api ref -
    Integration modules
    GLib / GConfig / GObject - libvirt - - gitlab - - i= ssues - - libvirt - github -
    Go XML - libvirt - - g= itlab - - issues - - libvirt - g= ithub - - api r= ef -
    D-Bus - libvirt - - gitlab - - i= ssues - - libvirt - github -
    Console Proxy - libvirt<= /a> - - g= itlab - - issues - - libvirt - g= ithub -
    CIM provider - libvirt - - gitlab - - is= sues - - libvirt - github -
    CIM utils - libvirt - - gitlab - - is= sues - - libvirt - github -
    SNMP - libvirt - - gitlab - - i= ssues - - libvirt - github -
    Application Sandbox - libvirt - - gitlab<= /a> - - issues - - libvirt - github<= /a> -
    Testing
    TCK - libvirt - - gitlab - - is= sues - - libvirt - github -
    Test API - gitlab= - - issues - - libvirt - github= -
    Continuous Integration Config - gitlab - - iss= ues - - libvirt - github -
    CIM Test - gitlab - - issues= - - libvirt - github -
    Documentation
    Publican Brand - gitlab= - - issues - - libvirt - github= -
    App Development Guide - gi= tlab - - issues - - libvirt - gi= thub -
    App Development Guide Python - gitlab - - issues - - libvirt - github -
    virsh Command Reference - git= lab - - issues - - libvirt - git= hub -
    - -

    Primary download site

    - -

    - Most modules have releases made available for download on the project - site via HTTPS. Some modules are instead made available at alternati= ve - locations, for example, the Perl binding is made available only on C= PAN. -

    - - - -

    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 o= nly - exception is at the start of the year where there are two 6 weeks ga= ps - (first release in the middle of Jan, then skip the Feb release), giv= ing - 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 h= ave - 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. -

    - -

    GIT source repository

    - -

    - All modules maintained by the libvirt project have their primary - source available in the project= GIT server. - 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 o= nly - occurs on the libvir-list 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 publ= ished - on this project site are signed with a GPG signature. You should alw= ays - verify the package signature before using the source to compile bina= ry - packages. The following key is currently used to generate the GPG - signatures: -

    - 
    -pub  4096R/10084C9C 2020-07-20 Ji=C5=99=C3=AD Denemark <jdenemar@redhat=
.com>
-Fingerprint=3D453B 6531 0595 5628 5547  1199 CA68 BE80 1008 4C9C
-
    - -

    - It can be downloaded from - this site 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=C5=99=
=C3=AD Denemark
-signed with his PGP key:
-
-pub  4096R/10084C9C 2020-07-20 Ji=C5=99=C3=AD Denemark <jdenemar@redhat=
.com>
-Fingerprint=3D453B 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=3D=3D
-=3DKnaO
------END PGP SIGNATURE-----
-
    - - - 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D +Downloads +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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 `__ + - `gitlab `__ + - `issues `__ + - `github `__ + - `api ref `__ + `changes `__ + +Language bindings +~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Module + - Releases + - GIT Repo + - Bug Tracker + - GIT Mirrors + - Resources + + * - C# + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + - + + * - Go + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + - `api ref `__ + + * - Java + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt = `__ + `github `__ + - + + * - OCaml + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + - + + * - Perl (Sys::Virt) + - `cpan `__ + - `gitlab `__ + - `issues `__ + - `libvirt = `__ + `github `__ + - `api ref `__ + `changes `__ + + * - PHP + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt `= __ + `github `__ + - + + * - Python + - `libvirt `__ + `pypi `__ + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + - + + * - Ruby + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt = `__ + `github `__ + - + + * - Rust + - `crates.io `__ + - `gitlab `__ + - `issues `__ + - `libvirt = `__ + `github `__ + - `api ref `__ + +Integration modules +~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Module + - Releases + - GIT Repo + - Bug Tracker + - GIT Mirrors + - Resources + + * - GLib / GConfig / GObject + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt = `__ + `github `__ + - + + * - Go XML + - `libvirt `__ + - `gitlab `__ + - `issues `= __ + - `libvirt `__ + `github `__ + - `api ref `__ + + * - D-Bus + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt = `__ + `github `__ + - + + * - Console Proxy + - `libvirt `__ + - `gitlab `__ + - `issues `= __ + - `libvirt `__ + `github `__ + - + + * - CIM provider + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt `= __ + `github `__ + - + + * - CIM utils + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt `= __ + `github `__ + - + + * - SNMP + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt = `__ + `github `__ + - + + * - Application Sandbox + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + - + +Testing +~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Module + - Releases + - GIT Repo + - Bug Tracker + - GIT Mirrors + + * - TCK + - `libvirt `__ + - `gitlab `__ + - `issues `__ + - `libvirt `= __ + `github `__ + + * - Test API + - + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + + * - Continuous Integration Config + - + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + + * - CIM Test + - + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + +Documentation +~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Module + - GIT Repo + - Bug Tracker + - GIT Mirrors + + * - Publican Brand + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + + * - App Development Guide + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + + * - App Development Guide Python + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + + * - virsh Command Reference + - `gitlab `__ + - `issues `__ + - `libvirt `__ + `github `__ + +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, f= or +example, the Perl binding is made available only on CPAN. + +- `libvirt.org HTTPS server `__ + +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 t= he +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 co= re +libvirt module. Other modules have independent ad-hoc releases with no fix= ed +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, t= he +stability of the code, or the API / ABI compatibility (libvirt API / ABI is +guaranteed stable forever). The rules applied for changing the libvirt ver= sion +number are: + +``major`` + incremented by 1 for the first release of the year (the Jan 15th releas= e) +``minor`` + reset to 0 with every major increment, otherwise incremented by 1 for e= ach + 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 arbitraril= y, and +maintenance releases appended a fourth digit. The language bindings will a= im to +use the same version number as the most recent core library API they suppo= rt. +The other modules have their own distinct release numbering sequence, thou= gh +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 f= orked +off the corresponding ``vmajor.minor.0`` formal release, and may have furt= her +releases of the form ``vmajor.minor.micro``. These maintenance branches sh= ould +only contain bug fixes, and no new features, backported from the master br= anch, +and are supported as long as at least one downstream distribution expresses +interest in a given branch. These maintenance branches are considered duri= ng 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 `__. + +GIT source repository +--------------------- + +All modules maintained by the libvirt project have their primary source +available in the `project GIT server `__. Each m= odule +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 us= e the +full set of features on these mirrors (e.g. pull requests on GitHub, so pl= ease +don't use them). All patch review and discussion only occurs on the +`libvir-list `__ mailing list. Also note that some repositor= ies +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 verif= y 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=C5=99=C3=AD Denemark + Fingerprint=3D453B 6531 0595 5628 5547 1199 CA68 BE80 1008 4C9C + +It can be downloaded from `this +site `__ 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) + uid [ unknown] Daniel Veillard + +:: + + -----BEGIN PGP SIGNED MESSAGE----- + Hash: SHA256 + + Starting from libvirt-6.6.0 the upstream releases will be done by Ji=C5= =99=C3=AD Denemark + signed with his PGP key: + + pub 4096R/10084C9C 2020-07-20 Ji=C5=99=C3=AD Denemark + Fingerprint=3D453B 6531 0595 5628 5547 1199 CA68 BE80 1008 4C9C + + This message is signed by the old signing key which was used for previo= us + 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=3D=3D + =3DKnaO + -----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 =3D [ 'csharp', 'dbus', 'docs', - 'downloads', 'drvbhyve', 'drvesx', 'drvhyperv', @@ -85,6 +84,7 @@ docs_rst_files =3D [ 'contribute', 'daemons', 'developer-tooling', + 'downloads', 'drivers', 'drvch', 'drvqemu', --=20 2.35.1 From nobody Wed May 15 09:11:24 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1646927582; cv=none; d=zohomail.com; s=zohoarc; b=OXuIETFf530biaji8flc/nhuyRCsJ9LZS+qXROwe3J7hen/3/ajm4Z1k5RaqF9qS6RXwuO+bAc30bDZU8VwoaDsSDRF64gnaR/vZM8XfQ6mThX3JUCacQfnkA0l06ujMuL8Cg/aE0COA0qmIJT46Byc4lYgjzEvxD+jfkldB5IQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927582; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=j3l/2RJUUBbGgaD66TQF+ObO6DnjJIy1JpVG0c9y5BE=; b=nhZmWtKhMCIo6tsELwwqMQVddavnie+uQXJYLKHGJsqVjTMbC7KlTDcIgLuHAY6/xouNuxlkt+2R0I2R+CryoWkPiOfDhNtB4hmJ9FcugOh1GqI+DnA0sVxJUR7HGPB89gbnG+gjriM9wlUPSdZneprEm9tnQfzmqkdtWfJanDU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1646927582951473.18881013869395; Thu, 10 Mar 2022 07:53:02 -0800 (PST) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-633-jezM43u8Pz-KDj-NG4u6Nw-1; Thu, 10 Mar 2022 10:51:54 -0500 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id D2AD5805F5C; Thu, 10 Mar 2022 15:51:44 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id A580B1457F07; Thu, 10 Mar 2022 15:51:44 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 4DC3A1966347; Thu, 10 Mar 2022 15:51:44 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B41211953576 for ; Thu, 10 Mar 2022 15:51:43 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 869527C029; Thu, 10 Mar 2022 15:51:43 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id CA2217C02A for ; Thu, 10 Mar 2022 15:51:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927582; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=j3l/2RJUUBbGgaD66TQF+ObO6DnjJIy1JpVG0c9y5BE=; b=WZ1Zx+j7NodFfG4LK9bJn0tGOMopqFF+HumUyk4OtWdhQ5BzjRksWf7KwmTf/EPXAkGfoh XeNAyMvJCdrydqP7DxdAG+w0JOy0O677Vxg6mLK/nE0CtrRL4JkUigFCplQqFIIzw8aKKt BUa/eef3K/W5n8txuxF3SI+LTFm5/4A= X-MC-Unique: jezM43u8Pz-KDj-NG4u6Nw-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 2/8] docs: Convert 'contact' page to rST Date: Thu, 10 Mar 2022 16:51:24 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1646927584901100001 Content-Type: text/plain; charset="utf-8" Preserve the 'irc' and 'email' anchors. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- 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 @@ - - - - -

    Contacting the project contributors

    - -
      - -

      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 handlin= g (potential) security issues - that should be used instead. So if your issue has security - implications, ignore the rest of this page and follow the - security process instead. -

      - -

      Mailing lists

      - -

      - There are three mailing-lists: -

      - -
      -
      = libvir-list@redhat.com (for development)
      -
      - Archives at https://www.redhat.com/archives/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 at https://www.redhat.com/archives/libvirt-users -
      -
      - This is a moderate volume mailing list. It is a place for discuss= ions - 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 AP= I(s)
        • -
      • Any other topics along these lines
        • -
      -
      - -
      libvirt-announce@redhat.com (for release notices)
      -
      - Archives at https://www.redhat.com/archives/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 - page. -

      - -

      IRC discussion

      - -

      - Some of the libvirt developers may be found on IRC on the OFTC IRC - 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 re= ply - promptly, so use the mailing-list if you don't get an answer on the = IRC - channel. -

      - - - 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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Contacting the project contributors +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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. Lib= virt +has `a dedicated process for handling (potential) security +issues `__ that should be used instead. So if your i= ssue +has security implications, ignore the rest of this page and follow the `se= curity +process `__ instead. + +:anchor:`` + +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 announc= ements + of new libvirt releases. + Subscribe to just this if you want to be notified of new releases, with= out + subscribing to either of the other mailing lists. + +It is recommended but not required that you subscribe before posting to th= e 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 appreciat= ed, +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 `__ page. + +:anchor:`` + +IRC discussion +-------------- + +Some of the libvirt developers may be found on IRC on the `OFTC +IRC `__ 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 ch= annel. 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 =3D [ docs_html_in_files =3D [ '404', 'cgroups', - 'contact', 'csharp', 'dbus', 'docs', @@ -81,6 +80,7 @@ docs_rst_files =3D [ 'coding-style', 'committer-guidelines', 'compiling', + 'contact', 'contribute', 'daemons', 'developer-tooling', --=20 2.35.1 From nobody Wed May 15 09:11:24 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1646927594; cv=none; d=zohomail.com; s=zohoarc; b=YzrJ7hF/TwUujAX6bR/HlCn/n0Q9kPRh77yPzQZ3dx5buSpfXFaQ0sX85JL7LWrEn3+ZZmEzFnceTcNudAW8oLlRtV9gNFsD+F3ZcTWnARedoM+rKcOFgzaq2U+deRrYdSwhdlGh8OjI9/X4hbSzLlyxl6HNqYT9UNikkbl7yo0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927594; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=S1fTtJdBcvPRpjUu0r7SS2D8tDUul3jCspwO+Rlsggg=; b=G9VeEJ7e4gRkPTvpfvasvNhfnqz+ry5d+wgN0rFTpnKxWdZteCY7Q5VRc0ustDEnd4AjJjnUd7OqEdWmdTEXqbb/KBycb9vbVwDAODSo78HZcmh95HfoeH/1/IXyIkQd7nGgonktAjqq7X4IDJJYbaRgmlz9G/NfCR3vInNduqw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1646927594928525.9315396170003; Thu, 10 Mar 2022 07:53:14 -0800 (PST) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-652-OSTHxc-sOym2Jo2osXpqbg-1; Thu, 10 Mar 2022 10:51:53 -0500 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id E703810665AF; Thu, 10 Mar 2022 15:51:45 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id D13944021C1; Thu, 10 Mar 2022 15:51:45 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id AE918195357C; Thu, 10 Mar 2022 15:51:45 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id DE033195FD6D for ; Thu, 10 Mar 2022 15:51:44 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id A0A717C02A; Thu, 10 Mar 2022 15:51:44 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 02C9E7C029 for ; Thu, 10 Mar 2022 15:51:43 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927593; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=S1fTtJdBcvPRpjUu0r7SS2D8tDUul3jCspwO+Rlsggg=; b=D9CBx8bSxRcPjAX/6nXXVHcRFWOA1/cqCWvzyN/+mtJBv5XNFB42L/t1ffWC6DIYZqn6Ch ejRimdfU8vIiTYaZ+NsTUDr6LyqrTIIs3U9ywduEwfEXteA6HOq0hLLsOh4d2xg/5MZef2 L+symW7qdtGSpJe7OuduUD+XdQnZKxQ= X-MC-Unique: OSTHxc-sOym2Jo2osXpqbg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 3/8] docs: Convert 'testapi' page to rST Date: Thu, 10 Mar 2022 16:51:25 +0100 Message-Id: <475e381d3be9762c441555ed1d9e5c1217f21ede.1646927156.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.10 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1646927597362100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- 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 =3D [ 'python', 'remote', 'storage', - 'testapi', 'testsuites', 'testtck', 'tlscerts', @@ -112,6 +111,7 @@ docs_rst_files =3D [ '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 @@ - - - - -

      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 configurati= ons - 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 o= ne - or more test case to define a given test scenario.

      -

      For more details you can look at:

      -       -

      Libvirt-test-API is maintained using - a GIT - repository, and comment, patches and reviews are carried - on the libvir-list development list.<= /p> - - 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +libvirt-test-API: Python based test suite +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Libvirt-test-API is a powerful test tool designed to complement existing l= ibvirt +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 th= e way +of the Python bindings. + +The test API currently covers: + +- domain: all classical lifetime operations, installation of various gues= ts + 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 sto= red 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 = `__ + file describing the test suite and how to write test cases and test + scenarios. + +Libvirt-test-API is maintained using `a GIT +repository `__, and comment, +patches and reviews are carried on the `libvir-list `__ +development list. --=20 2.35.1 From nobody Wed May 15 09:11:24 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1646927521; cv=none; d=zohomail.com; s=zohoarc; b=c/IxKJhV7XRgMNwNjuh3s5kEV3z6cWuimm1B6fTpQX8h2HVwzpe5yFD9qvk0Mwf3E0AhulJS7m4mLH0ulI4PwFTvrC6Ep2yPyO2vmc1gVbtdzz40CIntlNYSlIJMmpKHcdlUxCY8ky8WsIR0vlTjOfX89Hsug36iYFhPQ/L4d6A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927521; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=tOkgrIenPWKBP9A1Tberm7p37ZhtrT8Wk/wruBpBaF0=; b=MBc+YrZZIlZ1LybbCZulr4ptaVjtQEAIdOtuXG5sNAttK9iAg68nQPEf1FSwvBLrf8GrEBEKkneBSPetsz/rB8iuJa0s8cSGvIxEEiB7MXbV64HsUqFLDqNqvLLpj6duQ4Hg5DRBxNQaQCv8+Ra8ruL3Fz9s8hDjfVDV3elsph4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1646927521336231.02423058950694; Thu, 10 Mar 2022 07:52:01 -0800 (PST) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-270-0wYryFk_OBKiyZBPDJ4pfQ-1; Thu, 10 Mar 2022 10:51:56 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 06EF510665A9; Thu, 10 Mar 2022 15:51:50 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id E65F041136E0; Thu, 10 Mar 2022 15:51:49 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B49F7195FD66; Thu, 10 Mar 2022 15:51:49 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 53493195357C for ; Thu, 10 Mar 2022 15:51:49 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 229F27C029; Thu, 10 Mar 2022 15:51:49 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7C95C7C035 for ; Thu, 10 Mar 2022 15:51:44 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927520; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=tOkgrIenPWKBP9A1Tberm7p37ZhtrT8Wk/wruBpBaF0=; b=YGmMjEs3huOgmzbve/rn+QBjAsabt08fsWHBaD7K9TAveyrnZql7CbjG4M1jeFgEqKo9xt VN7IP7+i7Qq1XhQf6dBQDBYu7qswBEdmncQfKOD0LZ0V+YfUtxTL7Ng5OzZyJpw5AMxS5w ARP6Ey2CBpEsD65lMbdHZ79Ob3mWfMM= X-MC-Unique: 0wYryFk_OBKiyZBPDJ4pfQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 4/8] syntax-check: Don't check for non-reentrant functions in '.rst' files Date: Thu, 10 Mar 2022 16:51:26 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1646927522460100003 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- 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 =3D \ ^src/rpc/gendispatch\.pl$$ exclude_file_name_regexp--sc_prohibit_nonreentrant =3D \ - ^((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/wires= hark/util/genxdrstub\.pl|tools/virt-login-shell\.c$$) exclude_file_name_regexp--sc_prohibit_select =3D \ ^build-aux/syntax-check\.mk$$ --=20 2.35.1 From nobody Wed May 15 09:11:24 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1646927520; cv=none; d=zohomail.com; s=zohoarc; b=cg2n827cGnttrr0V6tyTgDpVCsRjOTlZWCvSKIYmzc7jaLDKJcaGnDQbRvgGSDRHVa650RuakCf+f7liHk10ruNDrPZEBbVoK8F0gQXnKV+Vgwo3oUHbukMo3VGh+i6tZvkR7BDI639kx/IDUMpYcRMhHSPGswScnKUsqHNFMGc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927520; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=vIQZSjr1ECT8h4/FdxEUs+F7elGMcA6rS/3bfa6p0go=; b=hxf3xdJBg/TVk5pI/FDfUiWKnZeC9jYXgFil9cWUCbuViqDH1cW0mjYtP9qRt5FXaSu86eiJ6q6SOIJMUib/UID7gLGsQAdtn5Lz+UZFu71uGp1WyEM4+z6Ls3eieE9tqxU+hR64k1isp3bzzHWLPKHGiaQIEHFtjZLTc3FEhPc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1646927520128119.34499387337394; Thu, 10 Mar 2022 07:52:00 -0800 (PST) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-632-YRm2J5qmOQK2QZRi318vHA-1; Thu, 10 Mar 2022 10:51:57 -0500 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 6C1D22A59550; Thu, 10 Mar 2022 15:51:52 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 56E77C07F53; Thu, 10 Mar 2022 15:51:52 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 04B6A195FD6C; Thu, 10 Mar 2022 15:51:52 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B2725195FD43 for ; Thu, 10 Mar 2022 15:51:50 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 519AD7C02A; Thu, 10 Mar 2022 15:51:50 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8F8BB7C029 for ; Thu, 10 Mar 2022 15:51:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927519; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=vIQZSjr1ECT8h4/FdxEUs+F7elGMcA6rS/3bfa6p0go=; b=DsoastICygLCNWhrkOPV5yajHeuh7ngxQiqqmQ5bTvF1yCBfD0NYPYdi+taOYZlYiFtP+7 A6k1KIb+eGjaD7ea1OKmxTSwmXnobNxzGyz0ZoTEB7GsR5tpyt5IiZyojIruKVxae426ft BLjdA7aN7xKLGmyDFreO09u7ScbDUWk= X-MC-Unique: YRm2J5qmOQK2QZRi318vHA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 5/8] docs: Convert 'nss' page to rST Date: Thu, 10 Mar 2022 16:51:27 +0100 Message-Id: <3c82383069c29ce1bd6cfaa074ef7e49df4f7759.1646927156.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1646928423748100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- 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 =3D [ 'internals', 'java', 'logging', - 'nss', 'pci-hotplug', 'php', 'python', @@ -103,6 +102,7 @@ docs_rst_files =3D [ '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 @@ - - - - -

      Libvirt NSS module

      - -
        - -

        - When it comes to managing guests and executing commands inside them, l= ogging - 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 ho= st - 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 on= to - 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 quest= ion. - Therefore users should consider the order in which they want the modul= es 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 serv= er - records. Therefore this is dependent on hostname provided by guests. T= hing - is, not all the guests out there provide one in DHCP transactions, or = not - every sysadmin out there believes all the guests. Hence libvirt implem= ents - second method in libvirt_guest module which does libvirt = guest - name to IP address translation (regardless of hostname set in the gues= t). -

        - -

        - 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 - gethostbyn= ame() - 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 g= ood - decision when implementing the internals of the function when they dec= ided - 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 possib= le - cases. What they have done instead is this pluggable mechanism. Small - plugins implementing nothing but specific technology for lookup proces= s are - provided and the function then calls those plugins. There is just one - configuration file that instructs the lookup function in which order s= hould - the plugins be called and which plugins should be loaded. For more info - reading = wiki - page 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 searc= h the - list trying to find matching record for given host name. When found, - matching IP address is returned to the caller. If not found, translati= on - process continues with the next plugin configured. At this point it is - important to stress the order in which plugins are called. Users shoul= d be - aware that a hostname might match in multiple plugins and right after = first - match, translation process is terminated and no other plugin is consul= ted. - Therefore, if there are two different records for the same host name u= sers - should carefully chose the lookup order. -

        - -

        Limitations

        - -
          -
        1. The libvirt NSS module matches only hostnames provi= ded by guest. - If the libvirt name and one advertised by guest differs, the latte= r is - matched. However, as of v3.0.0 there are two libvirt = NSS modules - translating both hostnames provided by guest and libvirt guest nam= es.
          2. -
        2. The module works only in that cases where IP addresses are assig= ned by - dnsmasq spawned by libvirt. Libvirt NATed networks are typical - example.
          3. -
        - -

        - 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 A= PI - 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 o= nly - 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 c= an - 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 st= ill - true for the libvirt NSS module. -

        - - 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Libvirt NSS module +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +When it comes to managing guests and executing commands inside them, loggi= ng +into guest operating system and doing the job is convenient. Users are use= d 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 dnsma= sq +(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 translati= on. +Users work around this problem by configuring their libvirt network to ass= ign +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 use= r is +trying to connect to, **files** module is consulted first (which boils dow= n 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 cons= ider +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 provid= e one +in DHCP transactions, or not every sysadmin out there believes all the gue= sts. +Hence libvirt implements second method in ``libvirt_guest`` module which d= oes +libvirt guest name to IP address translation (regardless of hostname set i= n 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 ``libvir= t`` +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() `__ or some va= riant +of it is called. This is a glibc function that takes a string containing t= he +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`` fi= le, +DNS, LDAP, etc.) it would not make much sense to create one big implementa= tion +containing all possible cases. What they have done instead is this pluggab= le +mechanism. Small plugins implementing nothing but specific technology for = lookup +process are provided and the function then calls those plugins. There is j= ust +one configuration file that instructs the lookup function in which order s= hould +the plugins be called and which plugins should be loaded. For more info re= ading +`wiki page `__ 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 t= he +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 matc= h in +multiple plugins and right after first match, translation process is termi= nated +and no other plugin is consulted. Therefore, if there are two different re= cords +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 ``libv= irt`` +NSS module.* These limitation are result of libvirt's internal implementat= ion. +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 costl= y. +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 me= rely +consults the list trying to find the match. Users can view the list themse= lves: + +:: + + virsh net-dhcp-leases $network + +where ``$network`` iterates through all running networks. So the module do= es +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`` libvi= rt +provides ``libvirt_guest`` NSS module that doesn't have this limitation. +However, the statement is still true for the ``libvirt`` NSS module. --=20 2.35.1 From nobody Wed May 15 09:11:24 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1646927584; cv=none; d=zohomail.com; s=zohoarc; b=P4YGlc5QN1ulnpSUkvYWQ5t1cTMyx4KKg/sAXYD2WDdtO+UlnPYR3ChNoHm8+cSvLILVeTQF5dQsWZlGbPjW4ztFI0TbFQkYreWYzcn6LF/e9uRLslkJF6S4pi++vWMM4+hZjhZ255lsuRT8rgbv3nPTOElekjV0wZkWkebQF8Q= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927584; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=1cIqJa/FDAvbZys6NbYd3d478M6NEsst3FrvTj7fi18=; b=Yn3HmM64sk1tljiag5BXWCCXJVO618qbd3G8EA6t/KYnFoATdLOK5sHBacl5B/TTaqeVdmBH7uyESKZKvrIIeoxZuBvDlP2A3ouvx36uf8VULHCGSA4wtwKcx+OgUwe7NdZkLsRqlEKrKhva+V7UxiOgXVON/b1N/90GTaqdqT0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1646927584168250.1197654815411; Thu, 10 Mar 2022 07:53:04 -0800 (PST) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-573-4Y07ESsFMXmdOAH3GJvv4g-1; Thu, 10 Mar 2022 10:52:25 -0500 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 9D54F1C068D7; Thu, 10 Mar 2022 15:52:23 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 85428401E32; Thu, 10 Mar 2022 15:52:23 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 4389A195FD66; Thu, 10 Mar 2022 15:52:23 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 089C51953576 for ; Thu, 10 Mar 2022 15:52:22 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id B5A957C029; Thu, 10 Mar 2022 15:52:21 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 11F587C02C for ; Thu, 10 Mar 2022 15:51:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927583; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=1cIqJa/FDAvbZys6NbYd3d478M6NEsst3FrvTj7fi18=; b=g/O27hI20m+MgW4IeCe0itzrY2bIpDcGzQ54miT2Uz1ktJBgBZs2biwRDN7cNQuMj8vXh8 55BEFuiF3hO6Hdww5eKhmUBvM36zCSglzdwrOqZkeLNohUSx9Xn70TJZSBBesmLU0mlYj9 VkOP5tjGq+KTcHiXUDRD3hrVq2n4zGs= X-MC-Unique: 4Y07ESsFMXmdOAH3GJvv4g-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 6/8] docs: Convert 'pci-hotplug' page to rST Date: Thu, 10 Mar 2022 16:51:28 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.10 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1646927585188100003 Content-Type: text/plain; charset="utf-8" One internal reference was modified to work properly. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- 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 =3D [ 'internals', 'java', 'logging', - 'pci-hotplug', 'php', 'python', 'remote', @@ -104,6 +103,7 @@ docs_rst_files =3D [ '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 @@ - - - - -

        PCI topology and hotplug

        - -
          - -

          - 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=3D'pci' index=3D'0' model=3D'pcie-root'/>
-<controller type=3D'pci' index=3D'1' model=3D'pcie-root-port'>
-  <model name=3D'pcie-root-port'/>
-  <target chassis=3D'1' port=3D'0x10'/>
-  <address type=3D'pci' domain=3D'0x0000' bus=3D'0x00' slot=3D'0x01' fu=
nction=3D'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 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=3D'pci' model=3D'pcie-root'/>
-<controller type=3D'pci' model=3D'pcie-root-port'/>
-<controller type=3D'pci' model=3D'pcie-root-port'/>
-<controller type=3D'pci' model=3D'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=3D'pci' model=3D'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=3D'pci' index=3D'0' model=3D'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=3D'pci' index=3D'0' model=3D'pci-root'>
-  <model name=3D'spapr-pci-host-bridge'/>
-  <target index=3D'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=3D'pci' model=3D'pci-root'/>
-<controller type=3D'pci' model=3D'pci-root'/>
-<controller type=3D'pci' model=3D'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, 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. -

          - - - 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +PCI topology and hotplug +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. 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 P= CI +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 dev= ices +will be hotplugged during the guest's lifetime, thus making it impossible = to +automatically provide the right amount of PCI controllers: any arbitrary n= umber +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 nee= d to +grow dynamically, so the responsibility of planning a suitable PCI topolog= y 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 + +:: + + + + + +
          + + +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 `__ 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 devic= e will +be hotplugged into the ``pcie-root-port`` controller. If you plan to hotpl= ug +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 + +:: + + + + + + +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: li= bvirt +will fill in the remaining details automatically. Note that you need to ad= d 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 t= he +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 + +:: + + + +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 l= ike + +:: + + + +where each of the 31 slots (from 0x01 to 0x1f) on the ``pci-root`` control= ler is +hotplug capable and can accept a legacy PCI device, either emulated or ass= igned +from the guest. + +ppc64 architecture +------------------ + +pseries machine type +~~~~~~~~~~~~~~~~~~~~ + +The default PCI topology for the ``pseries`` machine type looks like + +:: + + + + + + +The 31 slots, from 0x01 to 0x1f, on a ``pci-root`` controller are all hotp= lug +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-roo= t`` +controller. + +In order to take advantage of improved error reporting and recovering +capabilities, PCI devices assigned from the host need to be isolated by pl= acing +each on a separate ``pci-root`` controller, which has to be prepared in ad= vance +for hotplug to work: for example, add + +:: + + + + + +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-v= irt`` +guests is extremely uncommon, so you'll probably never need to add control= lers +other than ``pcie-root-port``. --=20 2.35.1 From nobody Wed May 15 09:11:24 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1646927549; cv=none; d=zohomail.com; s=zohoarc; b=X74D19M/O4Yct6sJmS/q92xG2MbuoUlXOxv7U0h9ypQL4bZOtnHrE0HNDW11TfBRxAKTM3zrmz8i3TWoAubgmiqVF5W1/xYv4x5kmpayE5V46ysEG6YhWMZC1vnsnJzsLtrfFCpZtZgkzipXKuAaF9KT7lTshcUoKfWQRt6nj+g= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927549; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=oPIZYA9aX9p6ODZjQ+OFa49NxHYyeK8xyzZZ2KL3ceQ=; b=IZNmxwatkL3W9i+LdS3innjZF89xTmINrbwF4+1atgJJtjcZTiD4dgMpzpHUdgqTPiajpKjBu2ZmMJW2JnWoP93fs7k1+DnZe0Zu5a57ZjmThZ3L8x1GgQ4BePIYWgjINsN9Ddp5TUgRlf3Jwon04ZTRUySHbhghCrlDkKNaVLQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 16469275499741015.3204342027144; Thu, 10 Mar 2022 07:52:29 -0800 (PST) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-480-50XXegcVMqOAj7NdT7KFmQ-1; Thu, 10 Mar 2022 10:52:27 -0500 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id D858E18E5345; Thu, 10 Mar 2022 15:52:24 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id C4537C15E6F; Thu, 10 Mar 2022 15:52:24 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 97A91195FD66; Thu, 10 Mar 2022 15:52:24 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 392C7195FD6C for ; Thu, 10 Mar 2022 15:52:23 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id D47A37C029; Thu, 10 Mar 2022 15:52:22 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 330257C02A for ; Thu, 10 Mar 2022 15:52:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927549; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=oPIZYA9aX9p6ODZjQ+OFa49NxHYyeK8xyzZZ2KL3ceQ=; b=ZFLAVjrVQNFeoFsjG+erJCC0JSNNwBAyelFUE5PgHNYvB1bpuQGxxuwd6U7mxQvAN5cvyw puINph4c4l0dRuxN1Xvx3duRkguyUlSSGEHzDUnSxWMZCK+bdlFGsYoVgD092FpttrJZ2l OO1lpakWO+u1UqyOoejKYsPcYAEcUMU= X-MC-Unique: 50XXegcVMqOAj7NdT7KFmQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 7/8] docs: Convert 'testtck' page to rST Date: Thu, 10 Mar 2022 16:51:29 +0100 Message-Id: <2f8108cca1aa17c105eedb88cd7eab9be577b95f.1646927156.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1646927550899100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- 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 =3D [ 'remote', 'storage', 'testsuites', - 'testtck', 'tlscerts', 'uri', 'windows', @@ -112,6 +111,7 @@ docs_rst_files =3D [ '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 @@ - - - - -

          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:

          - -

          Libvirt-TCK is maintained using - a GIT - repository, and comment, patches and reviews are carried - on the libvir-list development list.<= /p> - - 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +libvirt TCK : Technology Compatibility Kit +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The libvirt TCK provides a framework for performing testing of the integra= tion +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 scenari= os: + +- 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 li= bvirt + 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 wheth= er 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 `__ + presenting the project. +- The `page describing + VirtTCK `__ the inclus= ion of + libvirt-TCK as a Fedora Feature. + +Libvirt-TCK is maintained using `a GIT +repository `__, and comment, patch= es and +reviews are carried on the `libvir-list `__ development list. --=20 2.35.1 From nobody Wed May 15 09:11:24 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1646927585; cv=none; d=zohomail.com; s=zohoarc; b=O+EXXxjNG0V63RgCewnxhBd96Y9gq2uXgpIWgAphlMek+C5u4/4Qf1W7OhxapCVI1/rh2UelDEcATSW6GHedcb5FQ9j0fV1RkXAq94G5uGsvgp1KzJfFKBR/U1dMxc5wUIggpERBXs7c/lDX+99LYDqFlvEuGEORVxKe95oVpZU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646927585; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Fo+X0+rQnb+Pe5mIadTadukrQmfrrWsM0BfvVWLqOlE=; b=SfTZ3OqtnboNv5LAYK7rtacw/TELRiZCoc1quYcbvY1dPO6u5cRnTSOipOA50eFtTDZai0SS57/rsmF0Atd7Ue7Ryc8r6vo/7s3Ct+bnETl8sToTgNdm/3bLan9GTHI+ne8DhWEKuRrCB4ieJUzCsELtRaJZtAjJISXptomdfyw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1646927585457486.70197644440316; Thu, 10 Mar 2022 07:53:05 -0800 (PST) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-613-iNTSxsoTOoqchtjv8y_Txw-1; Thu, 10 Mar 2022 10:52:29 -0500 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 2CC1418E5356; Thu, 10 Mar 2022 15:52:27 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1566BC080B4; Thu, 10 Mar 2022 15:52:27 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id E063A195FD66; Thu, 10 Mar 2022 15:52:26 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 2B827195FD43 for ; Thu, 10 Mar 2022 15:52:24 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id F053A7C02A; Thu, 10 Mar 2022 15:52:23 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 57C907C029 for ; Thu, 10 Mar 2022 15:52:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646927585; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Fo+X0+rQnb+Pe5mIadTadukrQmfrrWsM0BfvVWLqOlE=; b=A1cmVIH0tebbeQrrz68y9dNYdReuzP2acSCqi8GtetmYpof21QkRTxP1gq9EEm8HGRjOqC 2LfJsk69hOVlHUlfcJdJOnNvSdeIuM4wJbWPk5lyI4YRJyGzxvUOtsaioFCAzJ1hedjGWy hl+tGXvu/wFORmuF/RygXsGUf8zMOrE= X-MC-Unique: iNTSxsoTOoqchtjv8y_Txw-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 8/8] docs: Convert 'testsuites' page to rST Date: Thu, 10 Mar 2022 16:51:30 +0100 Message-Id: <42c8eb06ae841dae6732620b511c82fd6a0d8b9d.1646927156.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1646927587374100007 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- 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 =3D [ 'python', 'remote', 'storage', - 'testsuites', 'tlscerts', 'uri', 'windows', @@ -111,6 +110,7 @@ docs_rst_files =3D [ '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 @@ - - - - -

          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 is a functional - test suite implemented using the - Perl bindings= - of libvirt. It is available separately as a - download, as a - package - in Fedora distributions, but best is probably to get - the version - from GIT. -
            • -
          • the libvirt-test-API is also a func= tional - test suite, but implemented using the - Python bindings - of libvirt. It is available separately as a - download= , - or directly get - the ver= sion - from GIT. -
            • -
          - - 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Test suites +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +There is a few test suites available to developers for testing a given ver= sion +of libvirt: + +- the internal test suite: present in the source code, it is run by devel= opers + 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 inter= acting + directly with virtualization functions properly. + +- the `TCK test suite `__ is a functional test suite implem= ented + using the `Perl bindings `__ of + libvirt. It is available separately as a + `download `__, as a + `package `__ + in Fedora distributions, but best is probably to get the `version from + GIT `__. + +- the `libvirt-test-API `__ is also a functional test suite= , but + implemented using the `Python bindings `__ of libvirt. It = is + available separately as a + `download `__, or directly= get + the `version from GIT `__. --=20 2.35.1