From nobody Fri May 10 12:06:15 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=1646668822; cv=none; d=zohomail.com; s=zohoarc; b=FI3jObsIZm8FsH8dpGKQl7cUe0f+bv5oAcxExjG9a43WA4BYNORJbnQ1lnV4PmNNYbxlEfZCg0hV7tnx/4vtjxORadMS3YZLn+ACy4g5oAIEHldb+JmrTasoCDqGaxmXFL3sXQgY/vA8qISL8jUiM4lVzIhUJj79MyczVHn+/lk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668822; 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=bK1H9deIv8Rb6QmN/0pSV3N4Pp9umvUboFd/Im83hDw=; b=Cbl9TtPoJUHPAlPt6bV2ruJa0lRtprsqtdqXrdexNCLFHM957NjpZ0vNSxMxDPhiZ2tciYf+OKPr8NkgDRskQ7HLWeXmcnwVVEGEmwn/Rx343mZi5k8OOzP+rMwo6KMrQSuatCcBJzdFKsE0tbaP8HsLeoYRuJMoetRgiPxGDnA= 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 1646668822190211.85435185512085; Mon, 7 Mar 2022 08:00:22 -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-360-hm2CBHmXPfy5awvqXZHmvg-1; Mon, 07 Mar 2022 11:00:16 -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 5C2FF101CC76; Mon, 7 Mar 2022 16:00:00 +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 43E2D4010FC6; Mon, 7 Mar 2022 16:00:00 +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 169C51931BE9; Mon, 7 Mar 2022 16:00:00 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 7563F1931BE5 for ; Mon, 7 Mar 2022 15:59:58 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 27CB07DE5E; Mon, 7 Mar 2022 15:59:58 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 819167D3CE for ; Mon, 7 Mar 2022 15:59:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668821; 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=bK1H9deIv8Rb6QmN/0pSV3N4Pp9umvUboFd/Im83hDw=; b=QjU00RO77B4IWN68GS6CYmfU0ZyK04wO/DXO1mDyAMA7bsia1n4h5xo5GRT0WedknOk1G1 PYJiaQmMpTVy3ML8qzx6haPVcEBGv+GXRE+LV68q9BgVHxOuBrh78edAwF/WVzN7ct6FHZ n3bsu6d7tgmHxSP3Wop5PSxo12HvI2E= X-MC-Unique: hm2CBHmXPfy5awvqXZHmvg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 01/17] docs: Remove 'virshcmdref' page Date: Mon, 7 Mar 2022 16:59:21 +0100 Message-Id: <6659dbe3f6d913640da4d52db33cf8e2c0589b45.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668823720100001 Content-Type: text/plain; charset="utf-8" The page isn't linked from anywhere and the project was archived. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/meson.build | 1 - docs/virshcmdref.html.in | 75 ---------------------------------------- 2 files changed, 76 deletions(-) delete mode 100644 docs/virshcmdref.html.in diff --git a/docs/meson.build b/docs/meson.build index 7e070d68ad..e348e64b8e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -76,7 +76,6 @@ docs_html_in_files =3D [ 'testtck', 'tlscerts', 'uri', - 'virshcmdref', 'windows', ] diff --git a/docs/virshcmdref.html.in b/docs/virshcmdref.html.in deleted file mode 100644 index f5993fabce..0000000000 --- a/docs/virshcmdref.html.in +++ /dev/null @@ -1,75 +0,0 @@ - - - - -

Virsh Command Reference

- -
    - -

    Description

    - -

    - The new Virsh Command Reference, for documenting the commands - in virsh, has recently been started. Only covering the Virtual - Networking commands initially, it will expand to cover all virsh - commands over time. -

    - -

    - If you would like to assist, content contributions are gladly accept= ed. - Please email Justin Clift - directly, or get in contact through any of the - official libvirt mailing lists. -

    - -

    Viewing Online

    - -

    - The latest version can be viewed directly online: -

    - - - -

    Downloading

    - -

    - The latest version of the Virsh Command Reference can be downloaded: -

    - - - -

    DocBook source GIT repository

    -

    - The DocBook source is archived in a git repository available on - gitlab.co= m. -

    - - - --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668825; cv=none; d=zohomail.com; s=zohoarc; b=YYIHH99CqCLDBqnGIcXixS4P1HrCCbOfsQ/jPvmO+vzamDZ9LNa8piQ+zVo5om4AErZr6vy5tJ4r1bt5Kt3roO/PID42ghNm25YVtrAYTL74zrt49Q6RDVczDk4pHmkazZG9H1m9e7IuxvvqtxZcV0+riDoPWZ3zBWoNGjEFnOc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668825; 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=j5fdy/VS0IwIBrjdRKc3uvh21SY6XOrP1B+MFfR21Ig=; b=dzZnjiwJbcY5wv6dm/+UySzFJXhj/vpmEWjfE/UwD3Eymw+cxz18AvcTKaozto53Lct8LySKMEm3cLDiM+N1DW8dqLTPTP6LTGX+W+IvGiS7vejh8VHO9ZPTUvoJHQZJzvQd5nbcYoPdIcbHE8Ixu/LZx9W3it98aWSGPBDrxSA= 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 16466688254986.982037079412862; Mon, 7 Mar 2022 08:00:25 -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-462-DICughQsMi2mXbRS7-9BpQ-1; Mon, 07 Mar 2022 11:00:17 -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 2A0E31815D07; Mon, 7 Mar 2022 16:00:01 +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 E9D364010FC6; Mon, 7 Mar 2022 16:00:00 +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 62DFD19305AE; Mon, 7 Mar 2022 16:00:00 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 773651931BE5 for ; Mon, 7 Mar 2022 15:59:59 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 36BCD7DE5E; Mon, 7 Mar 2022 15:59:59 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8B9647D3CE for ; Mon, 7 Mar 2022 15:59:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668824; 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=j5fdy/VS0IwIBrjdRKc3uvh21SY6XOrP1B+MFfR21Ig=; b=Etgn3nFYh9uVFlHQsk7sKppTxz3Cqj9+wnKQgfTwYg689G42cnJLTWMealZnDyKEb9/87T SsHvv+lN6MCxOeI5oGPZcW16HPIWzjAhTM+HzcX+jwJ5PPg7mkfal6AnxxTIDfYxMSzZYq SVgD/SqW5MExwTNFev5Vf46vjfSDT2k= X-MC-Unique: DICughQsMi2mXbRS7-9BpQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 02/17] docs: Drop 'devguide' page Date: Mon, 7 Mar 2022 16:59:22 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668829429100003 Content-Type: text/plain; charset="utf-8" The page is not referenced from anywhere and contains dead links for the output and links to old repos. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/devguide.html.in | 42 ------------------------------------------ docs/meson.build | 1 - 2 files changed, 43 deletions(-) delete mode 100644 docs/devguide.html.in diff --git a/docs/devguide.html.in b/docs/devguide.html.in deleted file mode 100644 index 2668e6f29e..0000000000 --- a/docs/devguide.html.in +++ /dev/null @@ -1,42 +0,0 @@ - - - - -

    libvirt Application Development Guides

    - -

    - The libvirt API is accessible from a number of programming languages. - At this time, there are application development guides available - which cover the C API and the Python API. Of the two, the Python gui= de - is currently the more comprehensive document. -

    - - - -

    Contributing content

    - -

    - These guides are written in DocBook and published with the - publican tool, which is also used for Fedora and Red Hat - documentation. The original content is provided in GIT and - any contributions to the guide are welcome. -

    - - 
    -# C language
-$ git clone https://libvirt.org/git/libvirt-appdev-guide.git
-
-# Python language
-$ git clone https://libvirt.org/git/libvirt-appdev-guide-python.git
-
-# Publican Style/Theme
-$ git clone =
https://libvirt.org/git/libvirt-publican.git
-
    - - - diff --git a/docs/meson.build b/docs/meson.build index e348e64b8e..3caaa76735 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -25,7 +25,6 @@ docs_html_in_files =3D [ 'contribute', 'csharp', 'dbus', - 'devguide', 'docs', 'downloads', 'drivers', --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668824; cv=none; d=zohomail.com; s=zohoarc; b=KQT0F6wvnCVYElLqx6A8Q/smCvGBponv1SEBn+j66f/OZnnkTzyf9bx/aAi991NbzRaDxOhj6rOpqACIghFZrgqyGDFxK1ZRqp34Yl4sWTBDnD2frc1KVNum4P+eaIeQhOKMMGbMoR8RHoQFFk4z7FYgr4RW6SaWJt/8nVoO7Fo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668824; 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=dXmmkfxXy6/GIyoKPFdz0Qd6YxFqSAR5eU7bZC8fS3s=; b=mTXEOw2Pv3rwIqwpRxkGtCpSx6gOmVM0zDdsqu4UUJCWjulvsmTCBNL3BIWxacRlJcnpaiysctJYxIxu3Ys28fzOW9d8d35fQ0JpBxu806xPERR46LjPTEs4UpI7GDMxdgN+eaXAilpP+QGc9GAX9xZ0KA3SMd0p/8BDb+GT0pk= 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 1646668823990963.8751329229657; Mon, 7 Mar 2022 08:00:23 -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-288-LXdWd1AJPzS0iet1FXXSYQ-1; Mon, 07 Mar 2022 11:00:17 -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 39BC1106655D; Mon, 7 Mar 2022 16:00:02 +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 1561340CFD14; Mon, 7 Mar 2022 16:00:02 +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 ACE541931BE9; Mon, 7 Mar 2022 16:00:01 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B701A196BB83 for ; Mon, 7 Mar 2022 16:00:00 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 86F547DE5E; Mon, 7 Mar 2022 16:00:00 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id A42CB7D3CE for ; Mon, 7 Mar 2022 15:59:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668822; 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=dXmmkfxXy6/GIyoKPFdz0Qd6YxFqSAR5eU7bZC8fS3s=; b=Zd3PxAj5rCSuqqqwbaNuxMiGe0pUXTGXjsP9gP7KJSomPxVA7f9TgJL4156B0XspzRZtUE t3+6/4z1XU5itlWBx9p3G5gd1mt5HIJaajVzJzO5KteeE+DqWTO0mxi7pxqtjIkLyVbVxO nPfT15Taz61NT7BVNbs8T9cHP0QCi48= X-MC-Unique: LXdWd1AJPzS0iet1FXXSYQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 03/17] docs: formatsnapshot: Convert to 'rst' Date: Mon, 7 Mar 2022 16:59:23 +0100 Message-Id: <014b0b8400fef80098e185fb54231720faf54a23.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668827857100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/formatsnapshot.html.in | 352 ------------------------------------ docs/formatsnapshot.rst | 297 ++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 298 insertions(+), 353 deletions(-) delete mode 100644 docs/formatsnapshot.html.in create mode 100644 docs/formatsnapshot.rst diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in deleted file mode 100644 index e481284aa8..0000000000 --- a/docs/formatsnapshot.html.in +++ /dev/null @@ -1,352 +0,0 @@ - - - - -

    Snapshot XML format

    - -
      - -

      Snapshot XML

      - -

      - Snapshots are one form - of domain state - capture. There are several types of snapshots: -

      -
      -
      disk snapshot
      -
      Contents of disks (whether a subset or all disks associated - with the domain) are saved at a given point of time, and can - be restored back to that state. On a running guest, a disk - snapshot is likely to be only crash-consistent rather than - clean (that is, it represents the state of the disk on a - sudden power outage, and may need fsck or journal replays to - be made consistent); on an inactive guest, a disk snapshot is - clean if the disks were clean when the guest was last shut - down. Disk snapshots exist in two forms: internal (file - formats such as qcow2 track both the snapshot and changes - since the snapshot in a single file) and external (the - snapshot is one file, and the changes since the snapshot are - in another file).
      -
      memory state (or VM state)
      -
      Tracks only the state of RAM and all other resources in use - by the VM. If the disks are unmodified between the time a VM - state snapshot is taken and restored, then the guest will - resume in a consistent state; but if the disks are modified - externally in the meantime, this is likely to lead to data - corruption.
      -
      full system
      -
      A combination of disk snapshots for all disks as well as VM - memory state, which can be used to resume the guest from where it - left off with symptoms similar to hibernation (that is, TCP - connections in the guest may have timed out, but no files or - processes are lost).
      -
      - -

      - Libvirt can manage all three types of snapshots. For now, VM - state (memory) snapshots are created only by - the virDomainSave(), virDomainSaveFlags, - and virDomainManagedSave() functions, and restored - via the virDomainRestore(), - virDomainRestoreFlags(), virDomainCreate(), - and virDomainCreateWithFlags() functions (as well - as via domain autostart). With managed snapshots, libvirt - tracks all information internally; with save images, the user - tracks the snapshot file, but libvirt provides functions such - as virDomainSaveImageGetXMLDesc() to work with - those files. -

      -

      Full system snapshots are created - by virDomainSnapshotCreateXML() with no flags, while - disk snapshots are created by the same function with - the VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY - flag. Regardless of the flags provided, restoration of the - snapshot is handled by - the virDomainRevertToSnapshot() function. For - these types of snapshots, libvirt tracks each snapshot as a - separate virDomainSnapshotPtr object, and maintains - a tree relationship of which snapshots descended from an earlier - point in time. -

      - -

      - Attributes of libvirt snapshots are stored as child elements of - the domainsnapshot element. At snapshot creation - time, normally only the name, description, - and disks elements are settable; the rest of the - fields are ignored on creation, and will be filled in by - libvirt in for informational purposes - by virDomainSnapshotGetXMLDesc(). However, when - redefining a snapshot (since 0.9.5), - with the VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE flag - of virDomainSnapshotCreateXML(), all of the XML - described here is relevant on input, even the fields that are - normally described as readonly for output. -

      -

      - Snapshots are maintained in a hierarchy. A domain can have a - current snapshot, which is the most recent snapshot compared to - the current state of the domain (although a domain might have - snapshots without a current snapshot, if snapshots have been - deleted in the meantime). Creating or reverting to a snapshot - sets that snapshot as current, and the prior current snapshot is - the parent of the new snapshot. Branches in the hierarchy can - be formed by reverting to a snapshot with a child, then creating - another snapshot. For now, the creation of external snapshots - when checkpoints exist is forbidden, although future work will - make it possible to integrate these two concepts. -

      -

      - The top-level domainsnapshot element may contain - the following elements: -

      -
      -
      name
      -
      The optional name for this snapshot. If the name is - omitted, libvirt will create a name based on the time of the - creation. -
      -
      description
      -
      An optional human-readable description of the snapshot. If - the description is omitted when initially creating the - snapshot, then this field will be empty. -
      -
      memory
      -
      On input, this is an optional request for how to handle VM - memory state. For an offline domain or a disk-only snapshot, - attribute snapshot must be no, since - there is no VM state saved; otherwise, the attribute can - be internal if the memory state is piggy-backed with - other internal disk state, or external along with - a second attribute file giving the absolute path - of the file holding the VM memory state. Si= nce - 1.0.1 -
      -
      disks
      -
      On input, this is an optional listing of specific - instructions for disk snapshots; it is needed when making a - snapshot of only a subset of the disks associated with a - domain, or when overriding the domain defaults for how to - snapshot each disk, or for providing specific control over - what file name is created in an external snapshot. On output, - this is fully populated to show the state of each disk in the - snapshot, including any properties that were generated by the - hypervisor defaults. For full system snapshots, this field is - ignored on input and omitted on output (a full system snapshot - implies that all disks participate in the snapshot process). - This element has a list of disk - sub-elements, describing anywhere from zero to all of the - disks associated with the domain. Since - 0.9.5 -
      -
      disk
      -
      This sub-element describes the snapshot properties of a - specific disk. The attribute name is - mandatory, and must match either the <target - dev=3D'name'/> (recommended) or an unambiguous - <source file=3D'name'/> of one of - the disk - devices specified for the domain at the time of the - snapshot. The attribute snapshot is - optional, and the possible values are the same as the - snapshot attribute for - disk devices - (no, internal, - or external). Some hypervisors like ESX - require that if specified, the snapshot mode must not - override any snapshot mode attached to the corresponding - domain disk, while others like qemu allow this field to - override the domain default. - -
      -
      source
      -
      If the snapshot mode is external (whether specified - or inherited), then there is an optional sub-element - source, with an attribute file - giving the name of the new file. - If source is not - given and the disk is backed by a local image file (not - a block device or remote storage), a file name is - generated that consists of the existing file name - with anything after the trailing dot replaced by the - snapshot name. Remember that with external - snapshots, the original file name becomes the read-only - snapshot, and the new file name contains the read-write - delta of all disk changes since the snapshot. -

      - The source element also may contain the - seclabel element (described in the - domain XML documentat= ion) - which can be used to override the domain security labeling p= olicy - for source. -

      -
      driver
      -
      An optional sub-element driver, - with an attribute type giving the driver type (= such - as qcow2), of the new file created by the external - snapshot of the new file. - - Optionally metadata_cache sub-element can be us= ed - with same semantics as the identically named subelement of t= he - domain definition disk's driver. -
      -
      seclabel
      -
      - - Since 1.2.2 the disk= element - supports an optional attribute type if the - snapshot attribute is set to external. - This attribute specifies the snapshot target storage type and = allows - to overwrite the default file type. The typ= e - attribute along with the format of the source - sub-element is identical to the source element us= ed in - domain disk definitions. See the - disk devices s= ection - documentation for further information. - - Libvirt currently supports the type element in th= e qemu - driver and supported values are file, block= - and network with a protocol of gluster - (since 1.2.2). -
      -
      -
      -
      creationTime
      -
      A readonly representation of the time this snapshot was - created. The time is specified in seconds since the Epoch, - UTC (i.e. Unix time). -
      -
      state
      -
      A readonly representation of the state of the domain at the - time this snapshot was taken. If a full system snapshot was - created, then this is the state of the domain at that - time. When the domain is reverted to this snapshot, the - domain's state will default to this state, unless overridden - by virDomainRevertToSnapshot() flags to revert to - a running or paused state. Additionally, this field can be the - value "disk-snapshot" (since 0.9.5) - when it represents only a disk snapshot (no VM memory state), - and reverting to this snapshot will default to an inactive - guest. -
      -
      parent
      -
      Readonly, present only if this snapshot has a parent. The - parent name is given by the sub-element name. The - parent relationship allows tracking a tree of related snapshots. -
      -
      domain
      -
      A readonly representation of the domain that this snapshot - was taken against. Older versions of libvirt stored only a - single child element, uuid; reverting to a snapshot like this - is risky if the current state of the domain differs from the - state that the domain was created in, and requires the use of - the VIR_DOMAIN_SNAPSHOT_REVERT_FORCE flag - in virDomainRevertToSnapshot(). Newer versions - of libvirt (since 0.9.5) store the - entire inactive domain - configuration at the time of the snapshot - (since 0.9.5). The domain will have - security-sensitive information omitted - unless the flag VIR_DOMAIN_SNAPSHOT_XML_SECURE is - provided on a read-write connection. -
      -
      cookie
      -
      An optional readonly representation of a save image cookie - containing additional data libvirt may need to properly - restore a domain from an active snapshot when such data cannot - be stored directly in the domain to maintain - compatibility with older libvirt or hypervisor. -
      -
      - -

      Examples

      - -

      Using this XML to create a disk snapshot of just vda on a qemu - domain with two disks:

      - 
      -<domainsnapshot>
-  <description>Snapshot of OS install and updates</description>
-  <disks>
-    <disk name=3D'vda'>
-      <source file=3D'/path/to/new'/>
-    </disk>
-    <disk name=3D'vdb' snapshot=3D'no'/>
-    <disk name=3D'vdc'>
-      <source file=3D'/path/to/newc'>
-        <seclabel model=3D'dac' relabel=3D'no'/>
-      </source>
-    </disk>
-  </disks>
-</domainsnapshot>
      - -

      will result in XML similar to this from - virDomainSnapshotGetXMLDesc():

      - 
      -<domainsnapshot>
-  <name>1270477159</name>
-  <description>Snapshot of OS install and updates</description>
-  <state>running</state>
-  <creationTime>1270477159</creationTime>
-  <parent>
-    <name>bare-os-install</name>
-  </parent>
-  <memory snapshot=3D'no'/>
-  <disks>
-    <disk name=3D'vda' snapshot=3D'external'>
-      <driver type=3D'qcow2'/>
-      <source file=3D'/path/to/new'/>
-    </disk>
-    <disk name=3D'vdb' snapshot=3D'no'/>
-  </disks>
-  <domain>
-    <name>fedora</name>
-    <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
-    <memory>1048576</memory>
-    ...
-    <devices>
-      <disk type=3D'file' device=3D'disk'>
-        <driver name=3D'qemu' type=3D'raw'/>
-        <source file=3D'/path/to/old'/>
-        <target dev=3D'vda' bus=3D'virtio'/>
-      </disk>
-      <disk type=3D'file' device=3D'disk' snapshot=3D'external'>
-        <driver name=3D'qemu' type=3D'raw'/>
-        <source file=3D'/path/to/old2'/>
-        <target dev=3D'vdb' bus=3D'virtio'/>
-      </disk>
-      ...
-    </devices>
-  </domain>
-</domainsnapshot>
      - -

      With that snapshot created, /path/to/old is the - read-only backing file to the new active - file /path/to/new. The <domain> - element within the snapshot xml records the state of the domain - just before the snapshot; a call - to virDomainGetXMLDesc() will show that the domain - has been changed to reflect the snapshot: -

      - 
      -<domain>
-  <name>fedora</name>
-  <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid>
-  <memory>1048576</memory>
-  ...
-  <devices>
-    <disk type=3D'file' device=3D'disk'>
-      <driver name=3D'qemu' type=3D'qcow2'/>
-      <source file=3D'/path/to/new'/>
-      <target dev=3D'vda' bus=3D'virtio'/>
-    </disk>
-    <disk type=3D'file' device=3D'disk' snapshot=3D'external'>
-      <driver name=3D'qemu' type=3D'raw'/>
-      <source file=3D'/path/to/old2'/>
-      <target dev=3D'vdb' bus=3D'virtio'/>
-    </disk>
-    ...
-  </devices>
-</domain>
      - - diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst new file mode 100644 index 0000000000..0ad397316c --- /dev/null +++ b/docs/formatsnapshot.rst @@ -0,0 +1,297 @@ +.. role:: since + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Snapshot XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Snapshot XML +------------ + +Snapshots are one form of `domain state +capture `__. There are several types of +snapshots: + +disk snapshot + Contents of disks (whether a subset or all disks associated with the do= main) + are saved at a given point of time, and can be restored back to that st= ate. + On a running guest, a disk snapshot is likely to be only crash-consiste= nt + rather than clean (that is, it represents the state of the disk on a su= dden + power outage, and may need fsck or journal replays to be made consisten= t); on + an inactive guest, a disk snapshot is clean if the disks were clean whe= n the + guest was last shut down. Disk snapshots exist in two forms: internal (= file + formats such as qcow2 track both the snapshot and changes since the sna= pshot + in a single file) and external (the snapshot is one file, and the chang= es + since the snapshot are in another file). +memory state (or VM state) + Tracks only the state of RAM and all other resources in use by the VM. = If the + disks are unmodified between the time a VM state snapshot is taken and + restored, then the guest will resume in a consistent state; but if the = disks + are modified externally in the meantime, this is likely to lead to data + corruption. +full system + A combination of disk snapshots for all disks as well as VM memory stat= e, + which can be used to resume the guest from where it left off with sympt= oms + similar to hibernation (that is, TCP connections in the guest may have = timed + out, but no files or processes are lost). + +Libvirt can manage all three types of snapshots. For now, VM state (memory) +snapshots are created only by the ``virDomainSave()``, ``virDomainSaveFlag= s``, +and ``virDomainManagedSave()`` functions, and restored via the +``virDomainRestore()``, ``virDomainRestoreFlags()``, ``virDomainCreate()``= , and +``virDomainCreateWithFlags()`` functions (as well as via domain autostart)= . With +managed snapshots, libvirt tracks all information internally; with save im= ages, +the user tracks the snapshot file, but libvirt provides functions such as +``virDomainSaveImageGetXMLDesc()`` to work with those files. + +Full system snapshots are created by ``virDomainSnapshotCreateXML()`` with= no +flags, while disk snapshots are created by the same function with the +``VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY`` flag. Regardless of the flags pro= vided, +restoration of the snapshot is handled by the ``virDomainRevertToSnapshot(= )`` +function. For these types of snapshots, libvirt tracks each snapshot as a +separate ``virDomainSnapshotPtr`` object, and maintains a tree relationshi= p of +which snapshots descended from an earlier point in time. + +Attributes of libvirt snapshots are stored as child elements of the +``domainsnapshot`` element. At snapshot creation time, normally only the +``name``, ``description``, and ``disks`` elements are settable; the rest o= f the +fields are ignored on creation, and will be filled in by libvirt in for +informational purposes by ``virDomainSnapshotGetXMLDesc()``. However, when +redefining a snapshot ( :since:`since 0.9.5` ), with the +``VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE`` flag of +``virDomainSnapshotCreateXML()``, all of the XML described here is relevan= t on +input, even the fields that are normally described as readonly for output. + +Snapshots are maintained in a hierarchy. A domain can have a current snaps= hot, +which is the most recent snapshot compared to the current state of the dom= ain +(although a domain might have snapshots without a current snapshot, if sna= pshots +have been deleted in the meantime). Creating or reverting to a snapshot se= ts +that snapshot as current, and the prior current snapshot is the parent of = the +new snapshot. Branches in the hierarchy can be formed by reverting to a sn= apshot +with a child, then creating another snapshot. For now, the creation of ext= ernal +snapshots when checkpoints exist is forbidden, although future work will m= ake it +possible to integrate these two concepts. + +The top-level ``domainsnapshot`` element may contain the following element= s: + +``name`` + + The optional name for this snapshot. If the name is omitted, libvirt wi= ll + create a name based on the time of the creation. + +``description`` + + An optional human-readable description of the snapshot. If the descript= ion + is omitted when initially creating the snapshot, then this field will be + empty. + +``memory`` + + On input, this is an optional request for how to handle VM memory state= . For + an offline domain or a disk-only snapshot, attribute ``snapshot`` must = be + ``no``, since there is no VM state saved; otherwise, the attribute can = be + ``internal`` if the memory state is piggy-backed with other internal di= sk + state, or ``external`` along with a second attribute ``file`` giving the + absolute path of the file holding the VM memory state. :since:`Since 1.= 0.1` + +``disks`` + + On input, this is an optional listing of specific instructions for disk + snapshots; it is needed when making a snapshot of only a subset of the = disks + associated with a domain, or when overriding the domain defaults for ho= w to + snapshot each disk, or for providing specific control over what file na= me is + created in an external snapshot. On output, this is fully populated to = show + the state of each disk in the snapshot, including any properties that w= ere + generated by the hypervisor defaults. For full system snapshots, this f= ield + is ignored on input and omitted on output (a full system snapshot impli= es + that all disks participate in the snapshot process). This element has a= list + of ``disk`` sub-elements, describing anywhere from zero to all of the d= isks + associated with the domain. :since:`Since 0.9.5` + + ``disk`` + + This sub-element describes the snapshot properties of a specific dis= k. + The attribute ``name`` is mandatory, and must match either the ```` (recommended) or an unambiguous ```` + of one of the `disk devices `__ + specified for the domain at the time of the snapshot. The attribute + ``snapshot`` is optional, and the possible values are the same as the + ``snapshot`` attribute for `disk devices + `__ (``no``, ``internal``, or + ``external``). Some hypervisors like ESX require that if specified, = the + snapshot mode must not override any snapshot mode attached to the + corresponding domain disk, while others like qemu allow this field to + override the domain default. + + ``source`` + + If the snapshot mode is external (whether specified or inherited), + then there is an optional sub-element ``source``, with an attribu= te + ``file`` giving the name of the new file. If ``source`` is not gi= ven + and the disk is backed by a local image file (not a block device = or + remote storage), a file name is generated that consists of the + existing file name with anything after the trailing dot replaced = by + the snapshot name. Remember that with external snapshots, the ori= ginal + file name becomes the read-only snapshot, and the new file name + contains the read-write delta of all disk changes since the snaps= hot. + + The ``source`` element also may contain the ``seclabel`` element + (described in the `domain XML documentation + `__) which can be used to override the + domain security labeling policy for ``source``. + + ``driver`` + + An optional sub-element ``driver``, with an attribute ``type`` gi= ving + the driver type (such as qcow2), of the new file created by the + external snapshot of the new file. Optionally ``metadata_cache`` + sub-element can be used with same semantics as the identically na= med + subelement of the domain definition disk's driver. + + ``seclabel`` + + :since:`Since 1.2.2` the ``disk`` element supports an optional attri= bute + ``type`` if the ``snapshot`` attribute is set to ``external``. This + attribute specifies the snapshot target storage type and allows to + overwrite the default ``file`` type. The ``type`` attribute along wi= th + the format of the ``source`` sub-element is identical to the ``sourc= e`` + element used in domain disk definitions. See the `disk devices + `__ section documentation for furth= er + information. Libvirt currently supports the ``type`` element in the = qemu + driver and supported values are ``file``, ``block`` and ``network`` = with + a protocol of ``gluster`` :since:`(since 1.2.2)` . + +``creationTime`` + + A readonly representation of the time this snapshot was created. The ti= me is + specified in seconds since the Epoch, UTC (i.e. Unix time). + +``state`` + + A readonly representation of the state of the domain at the time this + snapshot was taken. If a full system snapshot was created, then this is= the + state of the domain at that time. When the domain is reverted to this + snapshot, the domain's state will default to this state, unless overrid= den + by ``virDomainRevertToSnapshot()`` flags to revert to a running or paus= ed + state. Additionally, this field can be the value "disk-snapshot" ( + :since:`since 0.9.5`) when it represents only a disk snapshot (no VM me= mory + state), and reverting to this snapshot will default to an inactive gues= t. + +``parent`` + + Readonly, present only if this snapshot has a parent. The parent name is + given by the sub-element ``name``. The parent relationship allows track= ing a + tree of related snapshots. + +``domain`` + + A readonly representation of the domain that this snapshot was taken + against. Older versions of libvirt stored only a single child element, + uuid; reverting to a snapshot like this is risky if the current state o= f the + domain differs from the state that the domain was created in, and requi= res + the use of the ``VIR_DOMAIN_SNAPSHOT_REVERT_FORCE`` flag in + ``virDomainRevertToSnapshot()``. Newer versions of libvirt ( :since:`s= ince + 0.9.5` ) store the entire inactive `domain configuration + `__ at the time of the snapshot ( :since:`since 0.9.= 5` ). + The domain will have security-sensitive information omitted unless the = flag + ``VIR_DOMAIN_SNAPSHOT_XML_SECURE`` is provided on a read-write connecti= on. + +``cookie`` + + An optional readonly representation of a save image cookie containing + additional data libvirt may need to properly restore a domain from an a= ctive + snapshot when such data cannot be stored directly in the ``domain`` to + maintain compatibility with older libvirt or hypervisor. + +Examples +-------- + +Using this XML to create a disk snapshot of just vda on a qemu domain with= two +disks: + +:: + + + Snapshot of OS install and updates + + + + + + + + + + + + + +will result in XML similar to this from ``virDomainSnapshotGetXMLDesc()``: + +:: + + + 1270477159 + Snapshot of OS install and updates + running + 1270477159 + + bare-os-install + + + + + + + + + + + fedora + 93a5c045-6457-2c09-e56c-927cdf34e178 + 1048576 + ... + + + + + + + + + + + + ... + + + + +With that snapshot created, ``/path/to/old`` is the read-only backing file= to +the new active file ``/path/to/new``. The ```` element within the +snapshot xml records the state of the domain just before the snapshot; a c= all to +``virDomainGetXMLDesc()`` will show that the domain has been changed to re= flect +the snapshot: + +:: + + + fedora + 93a5c045-6457-2c09-e56c-927cdf34e178 + 1048576 + ... + + + + + + + + + + + + ... + + diff --git a/docs/meson.build b/docs/meson.build index 3caaa76735..adb7ac091e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -51,7 +51,6 @@ docs_html_in_files =3D [ 'formatnode', 'formatnwfilter', 'formatsecret', - 'formatsnapshot', 'formatstoragecaps', 'formatstorageencryption', 'goals', @@ -99,6 +98,7 @@ docs_rst_files =3D [ 'formatbackup', 'formatcheckpoint', 'formatdomain', + 'formatsnapshot', 'formatstorage', 'glib-adoption', 'hacking', --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668826; cv=none; d=zohomail.com; s=zohoarc; b=GFoB5FSKEiPMeHQ54g8wOF4PFyspwDyVjsv4dXOzfXqaS4BFVK94STWPzvv4ABrZPOPQDfHNdcsSJq1ERhyBYE4UOIwVu1td51ywQ+qZuoEQjx2XBEyUPt+ZlwybOk0KE7QVwmQHFdYWtRhTzZpq3w7+gwI/yX66TzTmpR5bOcY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668826; 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=UwNpQyqWoC5lhkIUncLClk961ijJ7Xk4yzRnoX4kig8=; b=jJZfbZ81f78WONe8+kMt9iqxYxviO03fPW6B4My8vDfPiK2y10E+kfKlTXKk5vWdoh0BnhJhw5SdUAk3oBBae3nvmugYVw/5wD0aKySfCE+lNVdVtWvTToto130qZhUPpO7olv32ZTH41NKd0GijJJHKmPCDlcPkA8sj+m2sRr4= 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 1646668826915969.4204408840415; Mon, 7 Mar 2022 08:00:26 -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-96-CzcQ9UnBOsqw6C2T7nswaA-1; Mon, 07 Mar 2022 11:00:21 -0500 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 8916F80159B; Mon, 7 Mar 2022 16:00:03 +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 69928400E43D; Mon, 7 Mar 2022 16:00:03 +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 26FBC1931BEA; Mon, 7 Mar 2022 16:00:03 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id E6778196BB8F for ; Mon, 7 Mar 2022 16:00:01 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 9F7B27D3CE; Mon, 7 Mar 2022 16:00:01 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id EDF6982769 for ; Mon, 7 Mar 2022 16:00:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668826; 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=UwNpQyqWoC5lhkIUncLClk961ijJ7Xk4yzRnoX4kig8=; b=gjlIIpBfLhkm+8BqdhchPD8zkR/Dnb5zPhLZlTQCN3+/bWzOXYHIb4xuwcONB7meTHGSlx GHZZSFdHtWxZOTBkE1GkgcH16A+0WS7EKeH7zYnCzpxaW00k1X2wAn35hws00XCXmUm2vK Ie0p4935H3H8A7exTxxzrU5RaySOglc= X-MC-Unique: CzcQ9UnBOsqw6C2T7nswaA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 04/17] docs: Convert 'goals' to rST Date: Mon, 7 Mar 2022 16:59:24 +0100 Message-Id: <00bfc4cbd54dead65223b21d2c6ef39f2b349f86.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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.2 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: 1646668832185100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/goals.html.in | 64 ---------------------------------------------- docs/goals.rst | 56 ++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 57 insertions(+), 65 deletions(-) delete mode 100644 docs/goals.html.in create mode 100644 docs/goals.rst diff --git a/docs/goals.html.in b/docs/goals.html.in deleted file mode 100644 index f1639338ad..0000000000 --- a/docs/goals.html.in +++ /dev/null @@ -1,64 +0,0 @@ - - - - -

      Terminology and goals

      -

      To avoid ambiguity about the terms used, here are the definitions - for some of the specific concepts used in libvirt documentation:

      -
        -
      • a node is a single physical machine
        • -
      • an hypervisor is a layer of software allowing to - virtualize a node in a set of virtual machines with possibly different - configurations than the node itself
        • -
      • a domain is an instance of an operating system - (or subsystem in the case of container virtualization) running on a - virtualized machine provided by the hypervisor
        • -
      -

      Now we can define the goal of libvirt: to provide a common and - stable layer sufficient to securely manage domains on a node, possibly - remote.

      -

      As a result, libvirt should provide all APIs needed to do the - management, such as: provision, create, modify, monitor, control, migr= ate - and stop the domains - within the limits of the support of the hypervi= sor - for those operations. - Not all hypervisors provide the same operations; but if an operation is - useful for domain management of even one specific hypervisor it is wor= th - providing in libvirt. - Multiple nodes - may be accessed with libvirt simultaneously, but the APIs are limited = to - single node operations. Node resource operations which are needed - for the management and provisioning of domains are also in the scope of - the libvirt API, such as interface setup, firewall rules, storage mana= gement - and general provisioning APIs. Libvirt will also provide the state - monitoring APIs needed to implement management policies, obviously - checking domain state but also exposing local node resource consumptio= n. -

      -

      This implies the following sub-goals:

      -
        -
      • All API can be carried remotely though secure APIs
        • -
      • While most API will be generic in term of hypervisor or Host OS, - some API may be targeted to a single virtualization environment - as long as the semantic for the operations from a domain management - perspective is clear
        • -
      • the API should allow to do efficiently and cleanly all the opera= tions - needed to manage domains on a node, including resource provisioning and - setup
        • -
      • the API will not try to provide high level virtualization polici= es or - multi-nodes management features like load balancing, but the API shoul= d be - sufficient so they can be implemented on top of libvirt
        • -
      • stability of the API is a big concern, libvirt should isolate - applications from the frequent changes expected at the lower level of = the - virtualization framework
        • -
      • the node being managed may be on a different physical machine th= an - the management program using libvirt, to this effect libvirt supports - remote access, but should only do so by using secure protocols.
        • -
      • libvirt will provide APIs to enumerate, monitor and use the reso= urces - available on the managed node, including CPUs, memory, storage, networ= king, - and NUMA partitions.
        • -
      -

      So libvirt is intended to be a building block for higher level - management tools and for applications focusing on virtualization of a - single node (the only exception being domain migration between node - capabilities which involves more than one node).

      - - diff --git a/docs/goals.rst b/docs/goals.rst new file mode 100644 index 0000000000..7385f27b61 --- /dev/null +++ b/docs/goals.rst @@ -0,0 +1,56 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Terminology and goals +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +To avoid ambiguity about the terms used, here are the definitions for some= of +the specific concepts used in libvirt documentation: + +- a **node** is a single physical machine +- an **hypervisor** is a layer of software allowing to virtualize a node = in a + set of virtual machines with possibly different configurations than the= node + itself +- a **domain** is an instance of an operating system (or subsystem in the= case + of container virtualization) running on a virtualized machine provided = by the + hypervisor + +Now we can define the goal of libvirt: **to provide a common and stable la= yer +sufficient to securely manage domains on a node, possibly remote**. + +As a result, libvirt should provide all APIs needed to do the management, = such +as: provision, create, modify, monitor, control, migrate and stop the doma= ins - +within the limits of the support of the hypervisor for those operations. N= ot all +hypervisors provide the same operations; but if an operation is useful for +domain management of even one specific hypervisor it is worth providing in +libvirt. Multiple nodes may be accessed with libvirt simultaneously, but t= he +APIs are limited to single node operations. Node resource operations which= are +needed for the management and provisioning of domains are also in the scop= e of +the libvirt API, such as interface setup, firewall rules, storage manageme= nt and +general provisioning APIs. Libvirt will also provide the state monitoring = APIs +needed to implement management policies, obviously checking domain state b= ut +also exposing local node resource consumption. + +This implies the following sub-goals: + +- All API can be carried remotely though secure APIs +- While most API will be generic in term of hypervisor or Host OS, some A= PI may + be targeted to a single virtualization environment as long as the seman= tic + for the operations from a domain management perspective is clear +- the API should allow to do efficiently and cleanly all the operations n= eeded + to manage domains on a node, including resource provisioning and setup +- the API will not try to provide high level virtualization policies or + multi-nodes management features like load balancing, but the API should= be + sufficient so they can be implemented on top of libvirt +- stability of the API is a big concern, libvirt should isolate applicati= ons + from the frequent changes expected at the lower level of the virtualiza= tion + framework +- the node being managed may be on a different physical machine than the + management program using libvirt, to this effect libvirt supports remote + access, but should only do so by using secure protocols. +- libvirt will provide APIs to enumerate, monitor and use the resources + available on the managed node, including CPUs, memory, storage, network= ing, + and NUMA partitions. + +So libvirt is intended to be a building block for higher level management = tools +and for applications focusing on virtualization of a single node (the only +exception being domain migration between node capabilities which involves = more +than one node). diff --git a/docs/meson.build b/docs/meson.build index adb7ac091e..afed104014 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -53,7 +53,6 @@ docs_html_in_files =3D [ 'formatsecret', 'formatstoragecaps', 'formatstorageencryption', - 'goals', 'governance', 'hooks', 'index', @@ -101,6 +100,7 @@ docs_rst_files =3D [ 'formatsnapshot', 'formatstorage', 'glib-adoption', + 'goals', 'hacking', 'libvirt-go', 'libvirt-go-xml', --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668862; cv=none; d=zohomail.com; s=zohoarc; b=T25VG7K5nUB0p5y8y2z+7zrnf1VlLd8OCeV5kNjwBtPeHWAUr+HRDw5FiZh3OxuPotISULfLwIWjCduxxbrzWacrAumxi+9QEvuOhKWHKnwEX5IJUGodJyfm42Sv8DTlx5IDxgS1hJcMt11wrs5cwSPfBA0sUTFoUT9NDf/KLBI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668862; 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=5gnSHRQvJeUaQICy2Us+YIdeGQqMVRNmOyf34b1WRZU=; b=kNNsHLj5mWaiqAilUGUlqmJYxGfnvBJkQYu5fCCoNfeLoGX4uv6RmTDeUa/XpmR5KjOX/JxOJWyHSkckSOlpEfQ0fWrC7ETKgcpnU+FFMOvgJ0/0c1+7hzWOKi31q/jHYrtDzTcTvuYa+rjQ+dACCPvxs+Qlq/vap6xm40jcCsA= 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 1646668862767211.39504542685768; Mon, 7 Mar 2022 08:01: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-246-B85R1cX_M-60AthkMarvAA-1; Mon, 07 Mar 2022 11:00:23 -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 4C951106656E; Mon, 7 Mar 2022 16:00:04 +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 3241040CFD06; Mon, 7 Mar 2022 16:00:04 +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 B99CF1931BEA; Mon, 7 Mar 2022 16:00:03 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 280BD19305AE for ; Mon, 7 Mar 2022 16:00:03 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id B3B3082764; Mon, 7 Mar 2022 16:00:02 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 11DAF82768 for ; Mon, 7 Mar 2022 16:00:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668862; 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=5gnSHRQvJeUaQICy2Us+YIdeGQqMVRNmOyf34b1WRZU=; b=gffMMGSGl4O4etAYfVnPHhTBVcleo0SeUWHSKFG85RfeB95u6yQjH7z4WBG9HSXXnqRWO6 3rFY7C8xLQA29WAeX/ZPsk/yk0dldj/RCKM/VmzZysBB/1UoM28+MhRZsnOqcPJaf9/q77 CjX1NwXm16+qyVGqrqRmD0exPJEGYEQ= X-MC-Unique: B85R1cX_M-60AthkMarvAA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 05/17] docs: Convert 'strategy' to rST Date: Mon, 7 Mar 2022 16:59:25 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668889863100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/meson.build | 2 +- docs/strategy.html.in | 133 ------------------------------------------ docs/strategy.rst | 105 +++++++++++++++++++++++++++++++++ 3 files changed, 106 insertions(+), 134 deletions(-) delete mode 100644 docs/strategy.html.in create mode 100644 docs/strategy.rst diff --git a/docs/meson.build b/docs/meson.build index afed104014..a719c268f6 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -66,7 +66,6 @@ docs_html_in_files =3D [ 'remote', 'securityprocess', 'storage', - 'strategy', 'support', 'testapi', 'testsuites', @@ -110,6 +109,7 @@ docs_rst_files =3D [ 'pci-addresses', 'platforms', 'programming-languages', + 'strategy', 'styleguide', 'submitting-patches', ] diff --git a/docs/strategy.html.in b/docs/strategy.html.in deleted file mode 100644 index 70b706b6de..0000000000 --- a/docs/strategy.html.in +++ /dev/null @@ -1,133 +0,0 @@ - - - - -

      Project Strategy

      - -

      - This document attempts to outline the libvirt project strategy for - the near future. Think of this as a high level vision or to-do list - setting the direction for the project and its developers to take. -

      - -

      Language consolidation

      - -

      - At time of writing libvirt uses the following languages: -

      - -
      -
      C
      -
      The core libvirt library, daemons, and helper tools are all writ= ten - in the C language.
      -
      Python
      -
      Various supporting build/test scripts are written in Python, with - compatibility for Python 3.
      -
      Perl
      -
      Various supporting build/test scripts are written in Perl. It is - also used for many syntax-check inline rules
      -
      Shell
      -
      Shell is used for some simple build/test scripts. At runtime - libvirt avoids shell except when using SSH tunnels to a remote - host
      -
      XSLT
      -
      The website uses XSLT for its templating system. The API - documentation is also autogenerated from an XML description - using XSLT
      -
      HTML
      -
      The website documentation is all written in plain HTML. Some HTML - is also auto-generated for API documentation
      -
      Meson
      -
      The core build system uses the new Meson build system
      -
      make
      -
      The syntax-check uses make recipes
      -
      awk/sed
      -
      A number of the syntax-check inline rules involve use of awk/sed - scripts
      -
      POD
      -
      The command line manual pages are typically written in Perl's POD - format, and converted to troff
      -
      - -

      - The wide range of languages used present a knowledge burden for - developers involved in libvirt, especially when there are multiple - languages all used in the same problem spaces. This is most notable - in the build system which uses a combination of Meson, shell, awk, - sed, Perl and Python, with debugging requiring - understanding of the interactions between many languages. The - popularity of Perl has declined, while Python has become - more popular. This directly influences the amount and quality of - contributions that can be expected for programs written in the - respective languages. -

      -

      - The C language has served libvirt well over the years, but its age s= hows - giving rise to limitations which negatively impact the project in te= rms - of code quality, reliability, and efficiency of development. Most no= tably - its lack of memory safety means that many code bugs become trivially - exploitable security flaws or denial of service. The lack of a high - level portable runtime results in a lot of effort being spent to - ensure cross platform portability. The modern languages Rust and Go - provide viable options for low level systems programming, in a way t= hat - is not practical with other common languages such as Python and Java. - There is thus a desire to make use of either Rust or Go, or a combin= ation - of both, to incrementally replace existing use of C, and also for - greenfield development. -

      -

      - With this in mind the libvirt project has set a vision for language - usage in the future: -

      - -
      -
      C
      -
      Large parts of the core libvirt library, daemons, and helper too= ls - will continue to make use in the C language. Integration of other - languages will be an incremental, targeted process where they can - bring the greatest benefit.
      -
      Rust / Go
      -
      Parts of the core libvirt library, daemons and helper tools are = to - leverage Rust or Go or both to replace C.
      -
      Meson
      -
      The core build system is to be written in Meson.
      -
      Python
      -
      Various supporting build/test scripts are written in Python 3 - compatible mode only.
      -
      reStructuredText
      -
      The website and command man pages are to be written in RST, using - Sphinx as the engine to convert to end user formats like HTML, tro= ff, - etc
      -
      - -

      - Some notable points from the above. Whether the core library / daemo= ns - will use Rust or Go internally is still to be decided based on more - detailed evaluation to identify the best fit. The need to link and e= mbed - this functionality in other processes has complex interactions both = at a - technical and non-technical level. For standalone helper tools, eith= er - language is viable, but there are fewer concerns around interactions= with - other in-process code from 3rd parties. Thus a different decision ma= y be - made for daemons/libraries vs tools. Any rewrite proposed for existi= ng - functionality will have to weigh up the benefits of the new code, - against the risk of introducing regressions with respect to the prev= ious - code. -

      - -

      - Using the RST format for documentation allows for the use of XSLT to= be - eliminated from the build process. RST and the Sphinx toolkit are wi= dely - used, as seen by the huge repository of content on - Read The Docs. - The ability to embed raw HTML in the RST docs will greatly facilitat= e its - adoption, avoiding the need for a big bang conversion of existing co= ntent. - Given the desire to eliminate Perl usage, replacing the use of POD - documentation for manual pages is an obvious followup task. RST is t= he - obvious choice to achieve alignment with the website, allowing the m= an - pages to be easily published online with other docs. It is further - anticipated that the current API docs generator which uses XSLT to - convert the XML API description would be converted to something which - generates RST using Python instead of XSLT. -

      - - diff --git a/docs/strategy.rst b/docs/strategy.rst new file mode 100644 index 0000000000..093764b645 --- /dev/null +++ b/docs/strategy.rst @@ -0,0 +1,105 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Project Strategy +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This document attempts to outline the libvirt project strategy for the near +future. Think of this as a high level vision or to-do list setting the dir= ection +for the project and its developers to take. + +Language consolidation +---------------------- + +At time of writing libvirt uses the following languages: + +C + The core libvirt library, daemons, and helper tools are all written in = the C + language. +Python + Various supporting build/test scripts are written in Python, with + compatibility for Python 3. +Perl + Various supporting build/test scripts are written in Perl. It is also u= sed + for many syntax-check inline rules +Shell + Shell is used for some simple build/test scripts. At runtime libvirt av= oids + shell except when using SSH tunnels to a remote host +XSLT + The website uses XSLT for its templating system. The API documentation = is + also autogenerated from an XML description using XSLT +HTML + The website documentation is all written in plain HTML. Some HTML is al= so + auto-generated for API documentation +Meson + The core build system uses the new Meson build system +make + The syntax-check uses make recipes +awk/sed + A number of the syntax-check inline rules involve use of awk/sed scripts +POD + The command line manual pages are typically written in Perl's POD forma= t, and + converted to troff + +The wide range of languages used present a knowledge burden for developers +involved in libvirt, especially when there are multiple languages all used= in +the same problem spaces. This is most notable in the build system which us= es a +combination of Meson, shell, awk, sed, Perl and Python, with debugging req= uiring +understanding of the interactions between many languages. The popularity o= f Perl +has declined, while Python has become more popular. This directly influenc= es the +amount and quality of contributions that can be expected for programs writ= ten in +the respective languages. + +The C language has served libvirt well over the years, but its age shows g= iving +rise to limitations which negatively impact the project in terms of code +quality, reliability, and efficiency of development. Most notably its lack= of +memory safety means that many code bugs become trivially exploitable secur= ity +flaws or denial of service. The lack of a high level portable runtime resu= lts in +a lot of effort being spent to ensure cross platform portability. The mode= rn +languages Rust and Go provide viable options for low level systems program= ming, +in a way that is not practical with other common languages such as Python = and +Java. There is thus a desire to make use of either Rust or Go, or a combin= ation +of both, to incrementally replace existing use of C, and also for greenfie= ld +development. + +With this in mind the libvirt project has set a vision for language usage = in the +future: + +C + Large parts of the core libvirt library, daemons, and helper tools will + continue to make use in the C language. Integration of other languages = will + be an incremental, targeted process where they can bring the greatest + benefit. +Rust / Go + Parts of the core libvirt library, daemons and helper tools are to leve= rage + Rust or Go or both to replace C. +Meson + The core build system is to be written in Meson. +Python + Various supporting build/test scripts are written in Python 3 compatibl= e mode + only. +reStructuredText + The website and command man pages are to be written in RST, using Sphin= x as + the engine to convert to end user formats like HTML, troff, etc + +Some notable points from the above. Whether the core library / daemons wil= l use +Rust or Go internally is still to be decided based on more detailed evalua= tion +to identify the best fit. The need to link and embed this functionality in= other +processes has complex interactions both at a technical and non-technical l= evel. +For standalone helper tools, either language is viable, but there are fewer +concerns around interactions with other in-process code from 3rd parties. = Thus a +different decision may be made for daemons/libraries vs tools. Any rewrite +proposed for existing functionality will have to weigh up the benefits of = the +new code, against the risk of introducing regressions with respect to the +previous code. + +Using the RST format for documentation allows for the use of XSLT to be +eliminated from the build process. RST and the Sphinx toolkit are widely u= sed, +as seen by the huge repository of content on `Read The +Docs `__. The ability to embed raw HTML in the R= ST +docs will greatly facilitate its adoption, avoiding the need for a big bang +conversion of existing content. Given the desire to eliminate Perl usage, +replacing the use of POD documentation for manual pages is an obvious foll= owup +task. RST is the obvious choice to achieve alignment with the website, all= owing +the man pages to be easily published online with other docs. It is further +anticipated that the current API docs generator which uses XSLT to convert= the +XML API description would be converted to something which generates RST us= ing +Python instead of XSLT. --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668840; cv=none; d=zohomail.com; s=zohoarc; b=KbxyVp4jXYcL1ehsawH6tjY2CGzI7m1q+vh8A6Pn/aqKJjdidLAzB5BSHA1ZeVlAOtES5/cSJd7fZ/HCQy669l5fbI+DNv/LRHQD84d37RRb19hcoUz3Pi1QmqsjHyb+SHK5G4Xf3hpc0CP3V3WDqyDw9oYgmztW/RdyCbUAnVg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668840; 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=0454eLxP36jpoFqLsLZjNrekov7B+/Cg1KSOmYg4+Kc=; b=JhcBWhAwLfXFJ6Zxn1iRqbpO+sVy8Satv9otVZeIxisfmSF4lldBrWUOJTTEJpv1s54P0CqgTRAtmCsxDN7kcs01u+CiuCkhFmGe8IGieyh3depIORlf1QN/oO9BqNO68+iyL0gq4L2PcaGPc5j4X/O4IARLDFVlz88LYpwPxJo= 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 1646668840889408.73785041766746; Mon, 7 Mar 2022 08:00:40 -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-486-XM6WyXubNuqVHE8l7-k_CQ-1; Mon, 07 Mar 2022 11:00:25 -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 B23678FA3C7; Mon, 7 Mar 2022 16:00:05 +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 9AE671457F16; Mon, 7 Mar 2022 16:00:05 +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 6C07319305AE; Mon, 7 Mar 2022 16:00:05 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 1387C196BB82 for ; Mon, 7 Mar 2022 16:00:04 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id CA0657DE5E; Mon, 7 Mar 2022 16:00:03 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3066E7D3CE for ; Mon, 7 Mar 2022 16:00:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668840; 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=0454eLxP36jpoFqLsLZjNrekov7B+/Cg1KSOmYg4+Kc=; b=E7syTLA6Abx4POgcEhz+YXWEQ6UZd8PtenrEXqDGMl07EaAdlOrqSFLMAUFiufnRIMTvI2 3X/zWm/z82zgrW9WTiljenf7B1aRd28y+JBj1NNKcjjYX7E8IMiiswXfMjRBS01/fcZjV4 G+4IQfKm1mGAopx6tj1rSKlYcMBhQRc= X-MC-Unique: XM6WyXubNuqVHE8l7-k_CQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 06/17] docs: Convert 'contribute' page to rST Date: Mon, 7 Mar 2022 16:59:26 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668842418100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa --- docs/contribute.html.in | 143 ---------------------------------------- docs/contribute.rst | 105 +++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 106 insertions(+), 144 deletions(-) delete mode 100644 docs/contribute.html.in create mode 100644 docs/contribute.rst diff --git a/docs/contribute.html.in b/docs/contribute.html.in deleted file mode 100644 index 790114a56d..0000000000 --- a/docs/contribute.html.in +++ /dev/null @@ -1,143 +0,0 @@ - - - - -

      Contributing to libvirt

      - -

      - This page provides guidance on how to contribute to the - libvirt project. -

      - -
        - -

        Contributions required

        - -

        - The libvirt project is always looking for new contributors to - participate in ongoing activities. While code development is a - major part of the project, assistance is needed in many other - areas including documentation writing, bug triage, testing, - application integration, website / wiki content management, - translation, branding, social media and more. The only - requirement is an interest in virtualization and desire to - help. -

        - -

        - The following is a non-exhaustive list of areas in which - people can contribute to libvirt. If you have ideas for - other contributions feel free to follow them. -

        - -
          -
        • Software development. The official upstream cod= e are - kept in various Git reposi= tories. - The core library / daemon (and thus the bulk of coding) is written= in C, - but there are language bindings written in Python, Perl, Java, Rub= y, - Php, OCaml and Go. There are also higher level wrappers - mapping libvirt into other object frameworks, such GLib, - CIM and SNMP. For those interested in working on the core parts of - libvirt, the contributor guidelines a= re - mandatory reading
          • -
        • Translation. All the libvirt modules aim to sup= port - translations where appropriate. All translation is - handling outside of the normal libvirt review process, - using the Fedora - instance of the Weblate tool. Thus people wishing - to contribute to translation should join the Fedora - translation team
          • -
        • Documentation. There are docbook guides on vari= ous - aspects of libvirt, particularly application development - guides for the C library and Python, and a virsh command - reference. There is thus scope for work by people who are - familiar with using or developing against libvirt, to - write further content for these guides. There is also a - need for people to review existing content for copy editing - and identifying gaps in the docs
          • -
        • Website / wiki curation. The bulk of the websit= e is - maintained in the primary GIT repository, while the wiki - site uses mediawiki. In both cases there is a need for - people to both write new content and curate existing - content to identify outdated information, improve its - organization and target gaps.
          • -
        • Testing. There are a number of tests suites tha= t can run - automated tests against libvirt. The coverage of the tests - is never complete, so there is a need for people to create - new test suites and / or provide environments to actually - run the tests in a variety of deployment scenarios.
          • -
        • Code analysis. The libvirt project has access t= o the coverity - tool to run static analysis against the codebase, however, - there are other types of code analysis that can be useful. - In particular fuzzing of the inputs can be very effective - at identifying problematic edge cases.
          • -
        • Security handling. Downstream (operating system= ) vendors - who distribute libvirt may wish to propose a person to - be part of the security handling team, to get early access - to information about forthcoming vulnerability fixes.
          • -
        • Evangelism. Work done by the project is of no b= enefit - unless the (potential) user community knows that it - exists. Thus it is critically important to the health - and future growth of the project, that there are a people - who evangelize the work created by the project. This can - take many forms, writing blog posts (about usage of features, - personal user experiences, areas for future work, and more), - syndicating docs and blogs via social media, giving user - group and/or conference talks about libvirt.
          • -
        • User assistance. Since documentation - is never perfect, there are inevitably cases where users - will struggle to attain a deployment goal they have, or - run into trouble with managing an existing deployment. - While some users may be able to contact a software vendor - to obtain support, it is common to rely on community help - forums such as libvirt users - mailing list, or sites such as - sta= ckoverflow. - People who are familiar with libvirt and have ability & - desire to help other users are encouraged to participate in - these help forums.
          • -
        - -

        Communication

        - -

        - For full details on contacting other project contributors - read the contact page. There - are two main channels that libvirt uses for communication - between contributors: -

        - -

        Mailing lists

        - -

        - The project has a number of - mailing lists for - general communication between contributors. - In general any design discussions and review - of contributions will take place on the mailing - lists, so it is important for all contributors - to follow the traffic. -

        - -

        Instant messaging / chat

        - -

        - Contributors to libvirt are encouraged to join the - IRC channel used by - the project, where they can have live conversations - with others members. -

        - -

        Student / outreach coding programs

        - -

        - Since 2016, the libvirt project directly participates as an - organization in the Google Summer of Code program. Prior to - this the project had a number of students in the program - via a joint application with the QEMU project. People are - encouraged to look at both the libvirt and QEMU programs - to identify potentially interesting projects to work on. -

        - - - diff --git a/docs/contribute.rst b/docs/contribute.rst new file mode 100644 index 0000000000..c95c8b59d2 --- /dev/null +++ b/docs/contribute.rst @@ -0,0 +1,105 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Contributing to libvirt +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This page provides guidance on how to contribute to the libvirt project. + +.. contents:: + +Contributions required +---------------------- + +The libvirt project is always looking for new contributors to participate = in +ongoing activities. While code development is a major part of the project, +assistance is needed in many other areas including documentation writing, = bug +triage, testing, application integration, website / wiki content managemen= t, +translation, branding, social media and more. The only requirement is an +interest in virtualization and desire to help. + +The following is a non-exhaustive list of areas in which people can contri= bute +to libvirt. If you have ideas for other contributions feel free to follow = them. + +- **Software development**. The official upstream code are kept in variou= s `Git + repositories `__. The core library / daemo= n (and + thus the bulk of coding) is written in C, but there are language bindin= gs + written in Python, Perl, Java, Ruby, Php, OCaml and Go. There are also = higher + level wrappers mapping libvirt into other object frameworks, such GLib,= CIM + and SNMP. For those interested in working on the core parts of libvirt,= the + `contributor guidelines `__ are mandatory reading +- **Translation**. All the libvirt modules aim to support translations wh= ere + appropriate. All translation is handling outside of the normal libvirt = review + process, using the `Fedora + instance = `__ of + the Weblate tool. Thus people wishing to contribute to translation shou= ld + join the Fedora translation team +- **Documentation**. There are docbook guides on various aspects of libvi= rt, + particularly application development guides for the C library and Pytho= n, and + a virsh command reference. There is thus scope for work by people who a= re + familiar with using or developing against libvirt, to write further con= tent + for these guides. There is also a need for people to review existing co= ntent + for copy editing and identifying gaps in the docs +- **Website / wiki curation**. The bulk of the website is maintained in t= he + primary GIT repository, while the wiki site uses mediawiki. In both cas= es + there is a need for people to both write new content and curate existing + content to identify outdated information, improve its organization and = target + gaps. +- **Testing**. There are a number of tests suites that can run automated = tests + against libvirt. The coverage of the tests is never complete, so there = is a + need for people to create new test suites and / or provide environments= to + actually run the tests in a variety of deployment scenarios. +- **Code analysis**. The libvirt project has access to the coverity tool = to run + static analysis against the codebase, however, there are other types of= code + analysis that can be useful. In particular fuzzing of the inputs can be= very + effective at identifying problematic edge cases. +- **Security handling**. Downstream (operating system) vendors who distri= bute + libvirt may wish to propose a person to be part of the security handling + team, to get early access to information about forthcoming vulnerability + fixes. +- **Evangelism**. Work done by the project is of no benefit unless the + (potential) user community knows that it exists. Thus it is critically + important to the health and future growth of the project, that there ar= e a + people who evangelize the work created by the project. This can take ma= ny + forms, writing blog posts (about usage of features, personal user + experiences, areas for future work, and more), syndicating docs and blo= gs via + social media, giving user group and/or conference talks about libvirt. +- **User assistance**. Since documentation is never perfect, there are + inevitably cases where users will struggle to attain a deployment goal = they + have, or run into trouble with managing an existing deployment. While s= ome + users may be able to contact a software vendor to obtain support, it is + common to rely on community help forums such as `libvirt users mailing + list `__, or sites such as + `stackoverflow. `__ + People who are familiar with libvirt and have ability & desire to help = other + users are encouraged to participate in these help forums. + +Communication +------------- + +For full details on contacting other project contributors read the +`contact `__ page. There are two main channels that libvirt = uses +for communication between contributors: + +Mailing lists +~~~~~~~~~~~~~ + +The project has a number of `mailing lists `__ for gen= eral +communication between contributors. In general any design discussions and = review +of contributions will take place on the mailing lists, so it is important = for +all contributors to follow the traffic. + +Instant messaging / chat +~~~~~~~~~~~~~~~~~~~~~~~~ + +Contributors to libvirt are encouraged to join the `IRC +channel `__ used by the project, where they can have live +conversations with others members. + +Student / outreach coding programs +---------------------------------- + +Since 2016, the libvirt project directly participates as an organization i= n the +`Google Summer of Code +program `__. Pr= ior to +this the project had a number of students in the program via a joint appli= cation +with the QEMU project. People are encouraged to look at both the libvirt a= nd +QEMU programs to identify potentially interesting projects to work on. diff --git a/docs/meson.build b/docs/meson.build index a719c268f6..bee7b3e6fc 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -22,7 +22,6 @@ docs_html_in_files =3D [ 'bugs', 'cgroups', 'contact', - 'contribute', 'csharp', 'dbus', 'docs', @@ -89,6 +88,7 @@ docs_rst_files =3D [ 'coding-style', 'committer-guidelines', 'compiling', + 'contribute', 'daemons', 'developer-tooling', 'drvqemu', --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668839; cv=none; d=zohomail.com; s=zohoarc; b=k605TtjmbhUZTZ/gY+VUan34loQw9FdSSLgOCCDsi1fZys8ExvkX9j5kaE7KSdqn9JqdLfLnQhAt0GgcjVaVTLLatTaIVcQZopwCxBikDmvG6sawk24aZO52aVKgNE3hXkyOUi4lHpdb0N8eKPrKb/I+WzuTuvL2i53VU0NZvgc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668839; 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=162RYyslnSIG3smtDwXxwzUumJHDMhY22k7Ka9h4ETw=; b=YYzkIVGmGqlgy9ODSKyZx6k35lPjfzoKdwTzvS5KUmgH5UGRxxxj6HML1F4qpPwZm0ZgsJ5NkB6UYTHkp4yRyfNAr5LoBshgzUr/CgWZmRr61jILJSQUqyJpAyIo9Wc2N9Y4lEOsBUc2E9NHdribFZrCP/Qeb2tXtJOeZwk1LXU= 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 1646668839481171.80233944683368; Mon, 7 Mar 2022 08:00:39 -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-610-S5w0kFKIPOemUNRD6-UOCg-1; Mon, 07 Mar 2022 11:00:30 -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 2465D85A5BE; Mon, 7 Mar 2022 16:00:08 +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 0469D1457F16; Mon, 7 Mar 2022 16:00:08 +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 C2B68196BB8E; Mon, 7 Mar 2022 16:00:07 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 22FB11931BEA for ; Mon, 7 Mar 2022 16:00:05 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id D85887DE5E; Mon, 7 Mar 2022 16:00:04 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3B79982769 for ; Mon, 7 Mar 2022 16:00:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668838; 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=162RYyslnSIG3smtDwXxwzUumJHDMhY22k7Ka9h4ETw=; b=H5YjCiislLNafwvcrNdaCe4hMAFZQLijGxzJ0qX9n246eYSR6EPhQPDd2m8fEWEJGZlQVU ldqeEFVk4PhOSO0EQi0Kz6XMkhJsSIV0hctTgu2f67r/gYudvNQhEJNtomW3MLfyX23BAk FA2s3fD52r+OcR9dUkuD+o1XeqIBlxM= X-MC-Unique: S5w0kFKIPOemUNRD6-UOCg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 07/17] docs: Convert 'bugs' page to rST Date: Mon, 7 Mar 2022 16:59:27 +0100 Message-Id: <194f4081a399c6fb3585f7d3d6888fc16ee6b566.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668840234100001 Content-Type: text/plain; charset="utf-8" Special care is given to preserve the 'quality' anchor in the 'bugs' page as we link to it directly from the gitlab issue template. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/bugs.html.in | 161 ---------------------------------------------- docs/bugs.rst | 125 +++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 126 insertions(+), 162 deletions(-) delete mode 100644 docs/bugs.html.in create mode 100644 docs/bugs.rst diff --git a/docs/bugs.html.in b/docs/bugs.html.in deleted file mode 100644 index 400c423518..0000000000 --- a/docs/bugs.html.in +++ /dev/null @@ -1,161 +0,0 @@ - - - - - -

        Bug reporting

        - -
          - -

          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. -

          - -

          Bug Tracking

          - -

          - If you are using libvirt binaries from a Linux distribution - check below for distribution specific bug reporting policies - first. -

          - -

          General libvirt bug reports

          - -

          - Bugs in upstream libvirt code should be reported as issues in the - appropriate project on GitLab= . - Before submitting a ticket, check the existing tickets to see if - the bug/feature is already tracked. -

          -

          - It's always a good idea to file bug reports, as the process of - filing the report always makes it easier to describe the - problem, and the bug number provides a quick way of referring to - the problem. However, not everybody in the community pays frequent - attention to issues, so after you file a bug, asking questions - and submitting patches on the libvirt - mailing lists will increase your bug's visibility and - encourage people to think about your problem. Don't hesitate to - ask questions on the list, as others may know of existing - solutions or be interested in collaborating with you on finding - a solution. Patches are always appreciated, and it's likely - that someone else has the same problem you do! -

          -

          - If you decide to write code, though, before you begin please - read the contributor guidelines, - especially the first point: "Discuss any large changes on the - mailing list first. Post patches early and listen to feedback." - Few development experiences are more discouraging than spending - a bunch of time writing a patch only to have someone point out a - better approach on list. -

          - - - -

          - Note bugs in language bindings and other sub-projects should be - reported to their corresponding git repository rather than the - main libvirt.git linked above. -

          - -

          Linux Distribution specific bug reports=

          -
            -
          • - If you are using binaries from Fedora, enter - tickets against the Fedora product and - the libvirt component. - -
            • -
          • -

            - If you are using binaries from Red Hat Enterprise - Linux, enter tickets against the Red Hat Enterprise - Linux product that you're using (e.g., Red Hat Enterprise - Linux 6) and the libvirt component. Red Hat - bugzilla has additional = guidance about getting support if - you are a Red Hat customer. -

            -
            • -
          • -

            - If you are using binaries from another Linux distribution - first follow their own bug reporting guidelines. -

            -
            • -
          • -

            - Finally, if you are a contributor to another Linux - distribution and would like to have your procedure for - filing bugs mentioned here, please mail the libvirt - development list. -

            -
            • -
          - - -

          How to file high quality bug reports

          - -

          - To increase the likelihood of your bug report being addressed it is - important to provide as much information as possible. When filing - libvirt bugs use this checklist to see if you are providing enough - information: -

          - -
            -
          • The version number of the libvirt build, or SHA1 of the GIT - commit
            • -
          • The hardware architecture being used
            • -
          • The name of the hypervisor (Xen, QEMU, KVM)
            • -
          • The XML config of the guest domain if relevant
            • -
          • For Xen hypervisor, the domain logfiles from /var/log/xen and - /var/log/libvirt/libxl
            • -
          • For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu
            • -
          - -

          - If the bug leads to a tool linked to libvirt crash, then the best - is to provide a backtrace along with the scenario used to get the - crash, the simplest is to run the program under gdb, reproduce the - steps leading to the crash and then issue a gdb "bt -a" command to - get the stack trace, attach it to the bug. Note that for the - data to be really useful libvirt debug information must be present - for example by installing libvirt debuginfo package on Fedora or - Red Hat Enterprise Linux (with debuginfo-install libvirt) prior - to running gdb.

          -

          - It may also happen that the libvirt daemon itself crashes or gets st= uck, - in the first case run it (as root) under gdb, and reproduce the sequ= ence - leading to the crash, similarly to a normal program provide the - "bt" backtrace information to where gdb will have stopped.
          - But if libvirtd gets stuck, for example seems to stop processing - commands, try to attach to the faulty daemon and issue a gdb command - "thread apply all bt" to show all the threads backtraces, as in:

          - 
           #  ps -o etime,pid `pgrep libvirt`
-... note the process id from the output
-# gdb /usr/sbin/libvirtd
-.... some information about gdb and loading debug data
-(gdb) attach $the_daemon_process_id
-....
-(gdb) thread apply all bt
-.... information to attach to the bug
-(gdb)
-
          - - - diff --git a/docs/bugs.rst b/docs/bugs.rst new file mode 100644 index 0000000000..152d734592 --- /dev/null +++ b/docs/bugs.rst @@ -0,0 +1,125 @@ +.. role:: anchor(raw) + :format: html + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Bug reporting +=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. + +Bug Tracking +------------ + +If you are using libvirt binaries from a Linux distribution check below for +distribution specific bug reporting policies first. + +General libvirt bug reports +--------------------------- + +Bugs in upstream libvirt code should be reported as issues in the appropri= ate +`project on GitLab. `__ Before submitting a ti= cket, +check the existing tickets to see if the bug/feature is already tracked. + +It's always a good idea to file bug reports, as the process of filing the = report +always makes it easier to describe the problem, and the bug number provide= s a +quick way of referring to the problem. However, not everybody in the commu= nity +pays frequent attention to issues, so after you file a bug, asking questio= ns and +submitting patches on `the libvirt mailing lists `__ will in= crease +your bug's visibility and encourage people to think about your problem. Do= n't +hesitate to ask questions on the list, as others may know of existing solu= tions +or be interested in collaborating with you on finding a solution. Patches = are +always appreciated, and it's likely that someone else has the same problem= you +do! + +If you decide to write code, though, before you begin please read the +`contributor guidelines `__, especially the first point: "Di= scuss +any large changes on the mailing list first. Post patches early and listen= to +feedback." Few development experiences are more discouraging than spending= a +bunch of time writing a patch only to have someone point out a better appr= oach +on list. + +- `View libvirt.git tickets = `__ +- `New libvirt.git ticket `__ + +Note bugs in language bindings and other sub-projects should be reported to +their corresponding git repository rather than the main libvirt.git linked +above. + +Linux Distribution specific bug reports +--------------------------------------- + +- If you are using binaries from **Fedora**, enter tickets against the + ``Fedora`` product and the ``libvirt`` component. + + - `View Fedora libvirt + tickets `__ + - `New Fedora libvirt + ticket `__ + +- If you are using binaries from **Red Hat Enterprise Linux**, enter tick= ets + against the Red Hat Enterprise Linux product that you're using (e.g., R= ed Hat + Enterprise Linux 6) and the ``libvirt`` component. Red Hat bugzilla has + `additional guidance `__ about getting sup= port + if you are a Red Hat customer. + +- If you are using binaries from another Linux distribution first follow = their + own bug reporting guidelines. + +- Finally, if you are a contributor to another Linux distribution and wou= ld + like to have your procedure for filing bugs mentioned here, please mail= the + libvirt development list. + +:anchor:`` + +How to file high quality bug reports +------------------------------------ + +To increase the likelihood of your bug report being addressed it is import= ant to +provide as much information as possible. When filing libvirt bugs use this +checklist to see if you are providing enough information: + +- The version number of the libvirt build, or SHA1 of the GIT commit +- The hardware architecture being used +- The name of the hypervisor (Xen, QEMU, KVM) +- The XML config of the guest domain if relevant +- For Xen hypervisor, the domain logfiles from /var/log/xen and + /var/log/libvirt/libxl +- For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu + +If the bug leads to a tool linked to libvirt crash, then the best is to pr= ovide +a backtrace along with the scenario used to get the crash, the simplest is= to +run the program under gdb, reproduce the steps leading to the crash and th= en +issue a gdb "bt -a" command to get the stack trace, attach it to the bug. = Note +that for the data to be really useful libvirt debug information must be pr= esent +for example by installing libvirt debuginfo package on Fedora or Red Hat +Enterprise Linux (with debuginfo-install libvirt) prior to running gdb. + +| It may also happen that the libvirt daemon itself crashes or gets stuck,= in + the first case run it (as root) under gdb, and reproduce the sequence le= ading + to the crash, similarly to a normal program provide the "bt" backtrace + information to where gdb will have stopped. +| But if libvirtd gets stuck, for example seems to stop processing command= s, try + to attach to the faulty daemon and issue a gdb command "thread apply all= bt" + to show all the threads backtraces, as in: + +:: + + # ps -o etime,pid `pgrep libvirt` + ... note the process id from the output + # gdb /usr/sbin/libvirtd + .... some information about gdb and loading debug data + (gdb) attach $the_daemon_process_id + .... + (gdb) thread apply all bt + .... information to attach to the bug + (gdb) diff --git a/docs/meson.build b/docs/meson.build index bee7b3e6fc..e92ce6bd9e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -19,7 +19,6 @@ docs_assets =3D [ docs_html_in_files =3D [ '404', - 'bugs', 'cgroups', 'contact', 'csharp', @@ -84,6 +83,7 @@ docs_rst_files =3D [ 'auth', 'bindings', 'best-practices', + 'bugs', 'ci', 'coding-style', 'committer-guidelines', --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668836; cv=none; d=zohomail.com; s=zohoarc; b=TBUgpBWflqxHYZorYlBHHrKZOHd6vDpg7cY9fui+By44YKrrNIEAEjIcdlVvGrl9xyICIWqwgvDaI5LrxEy0bMZ52q0Gz6BMTpIlPm0d2+gU6fEvK2JYKflrZAK8QL/At9/U+hPIunITUoQ+YHrJJUrnc3YZSrdAsXhulJgZn8s= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668836; 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=/+/GrIHIqQcTxJmQvmFc9N415dF4IPRPqavyIU0U/tU=; b=I4G51hbxG8kgAjnsG8Y5cRLR5AtfJTTvTxTrBZc1yHxBohs+SS5vFzdlLqGmBO13bloKuI3YokOpLl7/EJ0j/Z+Z5p86fBMWVx95Y6DQuKm/2lFnEfKSo51zTDelXmGnUsWQ4VT9JnjI0N0+o5DJnEzAGWjWq1pRqfV/yM61s0c= 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 1646668836944325.0210290460051; Mon, 7 Mar 2022 08:00:36 -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-330-I96oVY6jPPOcfkLbdt3oHg-1; Mon, 07 Mar 2022 11:00:28 -0500 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id BCD288FA3CE; Mon, 7 Mar 2022 16:00:08 +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 9F8F7400C849; Mon, 7 Mar 2022 16:00:08 +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 17397196BB81; Mon, 7 Mar 2022 16:00:08 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 614D41931BEA for ; Mon, 7 Mar 2022 16:00:06 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 325E27D3CE; Mon, 7 Mar 2022 16:00:06 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 542DC82764 for ; Mon, 7 Mar 2022 16:00:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668835; 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=/+/GrIHIqQcTxJmQvmFc9N415dF4IPRPqavyIU0U/tU=; b=gy0KoJ+9lU5Mg4aGt8pVCYcDLvJcDcvwXjUVpGz+zujxGYpg4QNV6K+LSWO/BrPZuqDwUZ NDV/owCAY3dt/rS/N99YWPNKPf9+eG7NA+F6XIm/dKI2FSLAhb+lBiZ7wkfMwt8Pso4WLr zOiluk8SuyKW8+PAlnbC2bQormS3hCg= X-MC-Unique: I96oVY6jPPOcfkLbdt3oHg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 08/17] docs: Convert 'errors' page to rST Date: Mon, 7 Mar 2022 16:59:28 +0100 Message-Id: <3e7fa7a3f2cd79664d9978d139273d952f97e83e.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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.2 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: 1646668838114100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/errors.html.in | 84 ---------------------------------- docs/errors.rst | 109 ++++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 110 insertions(+), 85 deletions(-) delete mode 100644 docs/errors.html.in create mode 100644 docs/errors.rst diff --git a/docs/errors.html.in b/docs/errors.html.in deleted file mode 100644 index ea4272822f..0000000000 --- a/docs/errors.html.in +++ /dev/null @@ -1,84 +0,0 @@ - - - - -

          Handling of errors

          -

          The main goals of libvirt when it comes to error handling are:

          -
            -
          • provide as much detail as possible
            • -
          • provide the information as soon as possible
            • -
          • dont force the library user into one style of error handling
            • -
          -

          As result the library provide both synchronous, callback based and -asynchronous error reporting. When an error happens in the library code the -error is logged, allowing to retrieve it later and if the user registered = an -error callback it will be called synchronously. Once the call to libvirt e= nds -the error can be detected by the return value and the full information for -the last logged error can be retrieved.

          -

          To avoid as much as possible troubles with a global variable in a -multithreaded environment, libvirt will associate when possible the errors= to -the current connection they are related to, that way the error is stored i= n a -dynamic structure which can be made thread specific. Error callback can be -set specifically to a connection with

          -

          So error handling in the code is the following:

          -
            -
          1. if the error can be associated to a connection for example when = failing - to look up a domain -
            1. if there is a callback associated to the connection set with <= a href=3D"html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorF= unc, - call it with the error information
            2. otherwise if there is a= global callback set with virSetErrorFunc, - call it with the error information
            3. otherwise call virDefaultErrorFunc - which is the default error function of the library issuing the err= or - on stderr
            4. save the error in the connection for later retri= eval with virCo= nnGetLastError
            2. -
          2. otherwise like when failing to create a hypervisor connection: -
            1. if there is a global callback set with virSetErrorFunc, - call it with the error information
            2. otherwise call virDefaultErrorFunc - which is the default error function of the library issuing the err= or - on stderr
            3. save the error in the connection for later retri= eval with virGetLas= tError
            3. -
          -

          In all cases the error information is provided as a virErrorPtr pointer to -read-only structure virEr= ror containing the -following fields:

          - -

          and then extra raw information about the error which may be initial= ized -to 0 or NULL if unused

          -
            -
          • str1, str2, str3: string information, usually str1 is the error - message format
            • -
          • int1, int2: integer information
            • -
          -

          So usually, setting up specific error handling with libvirt consist= of -registering a handler with virSetErrorFunc or -with virConnSe= tErrorFunc, -check the value of the code value, take appropriate action, if needed let -libvirt print the error on stderr by calling virDefaultErrorFunc. -For asynchronous error handing, set such a function doing nothing to avoid -the error being reported on stderr, and call virConnGetLastError or -virGetLastError when an API call returned an error value. It can be a good -idea to use virR= esetError or virConnResetLastError -once an error has been processed fully.

          -

          At the python level, there only a global reporting callback functio= n at -this point, see the error.py example about it:

          - 
          def handler(ctxt, err):
-    global errno
-
-    #print "handler(%s, %s)" % (ctxt, err)
-    errno =3D err
-
-libvirt.registerErrorHandler(handler, 'context')
          -

          the second argument to the registerErrorHandler function is passed = as the -first argument of the callback like in the C version. The error is a tuple -containing the same field as a virError in C, but cast to Python.

          - - diff --git a/docs/errors.rst b/docs/errors.rst new file mode 100644 index 0000000000..07c0fb1fc0 --- /dev/null +++ b/docs/errors.rst @@ -0,0 +1,109 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Handling of errors +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The main goals of libvirt when it comes to error handling are: + +- provide as much detail as possible +- provide the information as soon as possible +- dont force the library user into one style of error handling + +As result the library provide both synchronous, callback based and asynchr= onous +error reporting. When an error happens in the library code the error is lo= gged, +allowing to retrieve it later and if the user registered an error callback= it +will be called synchronously. Once the call to libvirt ends the error can = be +detected by the return value and the full information for the last logged = error +can be retrieved. + +To avoid as much as possible troubles with a global variable in a multithr= eaded +environment, libvirt will associate when possible the errors to the current +connection they are related to, that way the error is stored in a dynamic +structure which can be made thread specific. Error callback can be set +specifically to a connection with + +So error handling in the code is the following: + +#. if the error can be associated to a connection for example when failing= to + look up a domain + + #. if there is a callback associated to the connection set with + `virConnSetErrorFunc `__, + call it with the error information + #. otherwise if there is a global callback set with + `virSetErrorFunc `__, c= all it + with the error information + #. otherwise call + `virDefaultErrorFunc `__ + which is the default error function of the library issuing the error= on + stderr + #. save the error in the connection for later retrieval with + `virConnGetLastError `__ + +#. otherwise like when failing to create a hypervisor connection: + + #. if there is a global callback set with + `virSetErrorFunc `__, c= all it + with the error information + #. otherwise call + `virDefaultErrorFunc `__ + which is the default error function of the library issuing the error= on + stderr + #. save the error in the connection for later retrieval with + `virGetLastError `__ + +In all cases the error information is provided as a +`virErrorPtr `__ pointer to read-= only +structure `virError `__ containing t= he +following fields: + +- code: an error number from the + `virErrorNumber `__ enum +- domain: an enum indicating which part of libvirt raised the error see + `virErrorDomain `__ +- level: the error level, usually VIR_ERR_ERROR, though there is room for + warnings like VIR_ERR_WARNING +- message: the full human-readable formatted string of the error +- conn: if available a pointer to the + `virConnectPtr `__ connec= tion + to the hypervisor where this happened +- dom: if available a pointer to the + `virDomainPtr `__ domain + targeted in the operation + +and then extra raw information about the error which may be initialized to= 0 or +NULL if unused + +- str1, str2, str3: string information, usually str1 is the error message + format +- int1, int2: integer information + +So usually, setting up specific error handling with libvirt consist of +registering a handler with +`virSetErrorFunc `__ or with +`virConnSetErrorFunc `__,= check +the value of the code value, take appropriate action, if needed let libvirt +print the error on stderr by calling +`virDefaultErrorFunc `__.= For +asynchronous error handing, set such a function doing nothing to avoid the= error +being reported on stderr, and call virConnGetLastError or virGetLastError = when +an API call returned an error value. It can be a good idea to use +`virResetError `__ or +`virConnResetLastError = `__ +once an error has been processed fully. + +At the python level, there only a global reporting callback function at th= is +point, see the error.py example about it: + +:: + + def handler(ctxt, err): + global errno + + #print "handler(%s, %s)" % (ctxt, err) + errno =3D err + + libvirt.registerErrorHandler(handler, 'context') + +the second argument to the registerErrorHandler function is passed as the = first +argument of the callback like in the C version. The error is a tuple conta= ining +the same field as a virError in C, but cast to Python. diff --git a/docs/meson.build b/docs/meson.build index e92ce6bd9e..d0c1217351 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -39,7 +39,6 @@ docs_html_in_files =3D [ 'drvvirtuozzo', 'drvvmware', 'drvxen', - 'errors', 'firewall', 'formatcaps', 'formatdomaincaps', @@ -93,6 +92,7 @@ docs_rst_files =3D [ 'developer-tooling', 'drvqemu', 'drvch', + 'errors', 'formatbackup', 'formatcheckpoint', 'formatdomain', --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668842; cv=none; d=zohomail.com; s=zohoarc; b=FOscrpX/P2HixyhLzp6WGl7jtc6UnTbCAQHU9CJ9slTF1rPCQlEcxxVZb8vU8BV82o7OrXHgqZBXgO/fspYfWcdbIwd0azhRLHq72KcyJC7Wc4f77AKGB87b2xLzntFWqZFYu1XINRsxERSBdpGEuepFkL4yVOc272hIYm9XePQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668842; 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=OhPwOfNPrDFne0o/nvDRbIvkwVyCu54loEOhjrTfW8M=; b=XU8LGf5HZmJO11+v3e1HOHwq9Ko+jlBYiLTr9hV9yi16mygL8I0dUzFKnGtlraFLXw/SZWmdo9jAGGr2UdmtePu2Ftmt/iHQB9mGgIkAVv41fYggihOB4KP8Jo7FSTeyXXBIWmPOAmedt0QbRe6LrDoU65DFriYsU2Zd/CtNtTY= 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 1646668842968486.05191581597137; Mon, 7 Mar 2022 08:00:42 -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-407-WH38zqTUMVuV3NrRmKwDWw-1; Mon, 07 Mar 2022 11:00:38 -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 A1CDC805F5F; Mon, 7 Mar 2022 16:00:10 +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 892AA4010FC6; Mon, 7 Mar 2022 16:00:10 +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 64EEA19305AF; Mon, 7 Mar 2022 16:00:10 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id A03E91931BEA for ; Mon, 7 Mar 2022 16:00:07 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 71F367D3CE; Mon, 7 Mar 2022 16:00:07 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 988D17DE5E for ; Mon, 7 Mar 2022 16:00:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668842; 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=OhPwOfNPrDFne0o/nvDRbIvkwVyCu54loEOhjrTfW8M=; b=gtJihPcr2QbmBIG7TVrnrd4ph6VKBF+Oh/NbHdH7lPCCvZfJQ5Lem87g/W6iAi8l9yFJbZ IPAgsSJP0/Y9PdH3GIHc5LIljRKEzXM0jI1QfJ99tPtaliM5OEgfAHMR9e98hBQsNE07Kr dq3BhlWLZqOli9VrhiO4p4iHUx74M7M= X-MC-Unique: WH38zqTUMVuV3NrRmKwDWw-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 09/17] docs: Convert 'support' page to rST Date: Mon, 7 Mar 2022 16:59:29 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668844544100003 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/meson.build | 2 +- docs/support.html.in | 258 ------------------------------------------- docs/support.rst | 207 ++++++++++++++++++++++++++++++++++ 3 files changed, 208 insertions(+), 259 deletions(-) delete mode 100644 docs/support.html.in create mode 100644 docs/support.rst diff --git a/docs/meson.build b/docs/meson.build index d0c1217351..b3432cc6f6 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -63,7 +63,6 @@ docs_html_in_files =3D [ 'remote', 'securityprocess', 'storage', - 'support', 'testapi', 'testsuites', 'testtck', @@ -112,6 +111,7 @@ docs_rst_files =3D [ 'strategy', 'styleguide', 'submitting-patches', + 'support', ] # list of web targets to build for docs/web rule diff --git a/docs/support.html.in b/docs/support.html.in deleted file mode 100644 index 38f2f906e0..0000000000 --- a/docs/support.html.in +++ /dev/null @@ -1,258 +0,0 @@ - - - - -

          Support guarantees

          - -
            - -

            - This document will outline the support status / guarantees around the - very interfaces that libvirt exposes to applications and/or system - administrators. The intent is to help users understand what features= they - can rely upon in particular scenarios, and whether they are likely to - suffer disruption during upgrades. -

            - -

            Primary public API

            - -

            - The main public API provided by libvirt.so and described - in libvirt/libvirt.h exposes the primary hypervisor - agnostic management interface of libvirt. This API has the strongest - guarantee of any part of libvirt with a promise to keep backwards - compatibility forever. Specific details are as follows: -

            - -
            -
            Functions
            -
            Functions will never be removed from the public API, and will - never have parameters added, removed or changed in their signature. - IOW they will be ABI compatible forever. The semantics implied by - a specific set of parameters passed to the function will remain - unchanged. Where a parameter accepts a bitset of feature flags, or - an enumerated value, further flags / enum values may be supported - in the future. Where a parameter accepts one of a set of related - constants, further constants may be supported in the future. -
            -
            Struct types
            -
            Once defined in a release, struct definitions will never have any - fields add, removed or changed in any way. Their size and layout is - fixed forever. If a struct name starts with an underscore, it is - considered acceptable to rename it. Applications should thus always - use the corresponding typedef in preference to the struct name. -
            -
            Union types
            -
            Once defined in a release, union definitions will never have any - existing fields removed or changed. New union choices may be added, - provided that they don't change the size of the existing union - definition. If a struct name starts with an underscore, it is - considered acceptable to rename it. Applications should thus always - use the corresponding typedef in preference to the struct name. -
            -
            Type definitions
            -
            Most custom data types used in the APIs have corresponding typed= efs - provided for their stable names. The typedefs should always be used - in preference to the underlying data type name, as the latter are = not - guaranteed to be stable. -
            -
            Enumerations
            -
            Once defined in a release, existing enumeration values will never - be removed or renamed. New enumeration values may be introduced at - any time. Every enumeration will have a '_LAST' value which indica= tes - the current highest enumeration value, which may increase with new - releases. If an enumeration name starts with an underscore, it is - considered acceptable to rename it. Applications should thus always - use the corresponding typedef in preference to the enum name. -
            -
            Constants
            -
            Once defined in a release, existing constants will never be remo= ved - or have their value changed. Most constants are grouped into relat= ed - sets, and within each set, new constants may be introduced. APIs w= hich - use the constants may thus accept or return new constant values ov= er - time. -
            -
            Symbol versions
            -
            Where the platform library format permits, APIs defined in libvi= rt.so - library will have version information associated. Each API will be - tagged with the version in which it was introduced, and this won't - be changed thereafter. -
            -
            - -

            Hypervisor specific APIs

            - -

            - A number of hypervisor drivers provide additional libraries with hyp= ervisor - specific APIs, extending the core libvirt API. These add-on librarie= s follow - the same general principles described above, however, they are not - guaranteed to be preserved forever. The project reserves the right t= o remove - hypervisor specific APIs in any new release, or to change their sema= ntics. - That said the project will endeavour to maintain API compatibility f= or as long - as is practical. -

            - -

            - Use of some hypervisor specific APIs may result in the running guest= being - marked as "tainted" if the API is at risk of having unexpected inter= actions - with normal libvirt operations. An application which chooses to make= use of - hypervisor specific APIs should validate their operation with each n= ew release - of libvirt and each new release of the underlying hypervisor. The se= mantics - may change in unexpected ways, or have unforeseen interactions with = libvirt's - operation. -

            - -

            Error reporting

            - -

            - Most API calls are subject to failure and so will report error codes= and - messages. Libvirt defines error codes for a wide variety of scenario= s, some - represent very specific problems, while others are general purpose f= or - broad classes of problem. Over time the error codes reported are lia= ble - to change, usually changing from a generic error to a more specific = error. - Thus applications should be careful about checking for & taking = action - upon specific error codes, as their behaviour may change across rele= ases. -

            - -

            XML schemas

            - -

            - The main objects exposed via the primary libvirt public API are usua= lly - configured via XML documents following specific schemas. The XML sch= emas - are considered to be stable formats, whose compatibility will be mai= ntained - forever. Specific details are as follows: -

            - -
            -
            Attributes
            -
            Attributes defined on an XML element will never be removed or - renamed. New attributes may be defined. If the set of valid values - for an attribute are determined by an enumeration, the permitted - values will never be removed or renamed, only new values defined. - None the less, specific hypervisors may reject usage of certain - values according to their feature set. -
            -
            Elements
            -
            Elements defined will never be removed or renamed. New child - elements may be defined at any time. In places where only a - single instance of a named XML element is used, future versions - may be extended to permit multiple instances of the named XML - element to be used. An element which currently has no content - may later gain child elements. -
            -
            - -

            - Some hypervisor drivers may choose to allow use of hypervisor specif= ic - extensions to the XML documents. These extensions will always be - contained within a hypervisor specific XML namespace. There is gener= ally - no guarantee of long term support for the hypervisor specific extens= ions - across releases, though the project will endeavour to preserve them = as - long as is possible. Applications choosing to use hypervisor specific - extensions should validate their operation against new libvirt or - hypervisor releases. -

            - -

            Configuration files

            - -

            - A number of programs / daemons provided libvirt rely on host filesys= tem - configuration files. These configuration files are accompanied by au= geas - lens for easy manipulation by applications. There is in general no - guarantee that parameters available in the configuration file will be - preserved across releases, though the project will endeavour to pres= erve - them as long as is possible. If a configuration option is dropped fr= om - the file, the augeas lens will retain the ability to read that confi= guration - parameter, so that it is able to read & update historically modi= fied - files. - - The default configuration files ship with all parameters commented o= ut - such that a deployment relies on the built-in defaults of the applic= ation - in question. There is no guarantee that the defaults will remain the= same - across releases. A deployment that expects a particular value for a - configuration parameter should consider defining it explicitly, inst= ead - of relying on the defaults. -

            - -

            Hypervisor drivers

            - -

            - The libvirt project provides support for a wide variety of hypervisor - drivers. These drivers target certain versions of the hypervisor's - underlying management APIs. In general libvirt aims to work with any - hypervisor version that is still broadly supported by its vendor. - When a vendor discontinues support for a particular hypervisor - version it will be dropped by libvirt. Libvirt may choose to drop - support for a particular hypervisor version prior to the vendor - ending support, if it deems that the likely usage is too small to - justify the ongoing maintenance cost. -

            -

            - Each hypervisor release will implement a distinct subset of features - that can be expressed in the libvirt APIs and XML formats. While the - XML schema syntax will be stable across releases, libvirt is unable - to promise that it will always be able to support usage of the same - features across hypervisor releases. Where a hypervisor changes the - way a feature is implemented, the project will endeavour to adapt - to the new implementation to provide the same semantics. In cases - where the feature is discontinued by the hypervisor, libvirt will - return an error indicating it is not supported. Likewise libvirt will - make reasonable efforts to keep API calls working across hypervisor - releases even if the underlying implementation changes. In cases whe= re - this is impossible, a suitable error will be reported. The list of - APIs which have implementations is detail= ed separately. -

            - -

            RPC protocol

            - -

            - For some hypervisor drivers, the libvirt.so library communicates with - separate libvirt daemons to perform work. This communication takes - place over a binary RPC protocol defined by libvirt. The protocol us= es - the XDR format for data encoding, and the message packet format is - defined in libvirt source code. -

            -

            - Applications are encouraged to use the primary libvirt.so library wh= ich - transparently talks to the daemons, so that they are not exposed to = the - hypervisor driver specific details. None the less, the RPC protocol - associated with the libvirtd is considered to be a long term stable = ABI. - It will only ever have new messages added to it, existing messages w= ill - not be removed, nor have their contents changed. Thus if an applicat= ion - does wish to provide its own client side implementation of the RPC - protocol this is supported, with the caveat that the application will - loose the ability to work with certain hypervisors libvirt supports. - The project reserves the right to define new authentication and encr= yption - options for the protocol, and the defaults used in this area may cha= nge - over time. This is particularly true of the TLS ciphers permitted. T= hus - applications choosing to implement the RPC protocol must be prepared= to - track support for new security options. If defaults are changed, how= ever, - it will generally be possible to reconfigure the daemon to use the o= ld - defaults, albeit with possible implications for system security. -

            - -

            - Other daemons besides, libvirtd, also use the same RPC protocol, but - with different message types defined. These RPC protocols are all - considered to be private implementations that are liable to change - at any time. Applications must not attempt to talk to these other - daemons directly. -

            - -

            virsh client

            - -

            - The virsh program provides a simple client to interact with an arbit= rary libvirt - hypervisor connection. Since it uses the primary public API of libvi= rt, it should - generally inherit the guarantees associated with that API, and with = the hypervisor - driver. The commands that virsh exposes, and the arguments they acce= pt are all - considered to be long term stable. Existing commands and arguments w= ill not be - removed or renamed. New commands and arguments may be added in new r= eleases. - The text output format produced by virsh commands is not generally g= uaranteed to - be stable if it contains compound data (eg formatted tables or lists= ). Commands - which output single data items (ie an object name, or an XML documen= t), can be - treated as having stable format. -

            - - - diff --git a/docs/support.rst b/docs/support.rst new file mode 100644 index 0000000000..f285f63c55 --- /dev/null +++ b/docs/support.rst @@ -0,0 +1,207 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Support guarantees +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +This document will outline the support status / guarantees around the very +interfaces that libvirt exposes to applications and/or system administrato= rs. +The intent is to help users understand what features they can rely upon in +particular scenarios, and whether they are likely to suffer disruption dur= ing +upgrades. + +Primary public API +------------------ + +The main public API provided by ``libvirt.so`` and described in +``libvirt/libvirt.h`` exposes the primary hypervisor agnostic management +interface of libvirt. This API has the strongest guarantee of any part of +libvirt with a promise to keep backwards compatibility forever. Specific d= etails +are as follows: + +Functions + Functions will never be removed from the public API, and will never have + parameters added, removed or changed in their signature. IOW they will = be ABI + compatible forever. The semantics implied by a specific set of paramete= rs + passed to the function will remain unchanged. Where a parameter accepts= a + bitset of feature flags, or an enumerated value, further flags / enum v= alues + may be supported in the future. Where a parameter accepts one of a set = of + related constants, further constants may be supported in the future. +Struct types + Once defined in a release, struct definitions will never have any field= s add, + removed or changed in any way. Their size and layout is fixed forever. = If a + struct name starts with an underscore, it is considered acceptable to r= ename + it. Applications should thus always use the corresponding typedef in + preference to the struct name. +Union types + Once defined in a release, union definitions will never have any existi= ng + fields removed or changed. New union choices may be added, provided tha= t they + don't change the size of the existing union definition. If a struct name + starts with an underscore, it is considered acceptable to rename it. + Applications should thus always use the corresponding typedef in prefer= ence + to the struct name. +Type definitions + Most custom data types used in the APIs have corresponding typedefs pro= vided + for their stable names. The typedefs should always be used in preferenc= e to + the underlying data type name, as the latter are not guaranteed to be s= table. +Enumerations + Once defined in a release, existing enumeration values will never be re= moved + or renamed. New enumeration values may be introduced at any time. Every + enumeration will have a '_LAST' value which indicates the current highe= st + enumeration value, which may increase with new releases. If an enumerat= ion + name starts with an underscore, it is considered acceptable to rename i= t. + Applications should thus always use the corresponding typedef in prefer= ence + to the enum name. +Constants + Once defined in a release, existing constants will never be removed or = have + their value changed. Most constants are grouped into related sets, and = within + each set, new constants may be introduced. APIs which use the constants= may + thus accept or return new constant values over time. +Symbol versions + Where the platform library format permits, APIs defined in libvirt.so l= ibrary + will have version information associated. Each API will be tagged with = the + version in which it was introduced, and this won't be changed thereafte= r. + +Hypervisor specific APIs +------------------------ + +A number of hypervisor drivers provide additional libraries with hypervisor +specific APIs, extending the core libvirt API. These add-on libraries foll= ow the +same general principles described above, however, they are **not** guarant= eed to +be preserved forever. The project reserves the right to remove hypervisor +specific APIs in any new release, or to change their semantics. That said = the +project will endeavour to maintain API compatibility for as long as is +practical. + +Use of some hypervisor specific APIs may result in the running guest being +marked as "tainted" if the API is at risk of having unexpected interaction= s with +normal libvirt operations. An application which chooses to make use of +hypervisor specific APIs should validate their operation with each new rel= ease +of libvirt and each new release of the underlying hypervisor. The semantic= s may +change in unexpected ways, or have unforeseen interactions with libvirt's +operation. + +Error reporting +--------------- + +Most API calls are subject to failure and so will report error codes and +messages. Libvirt defines error codes for a wide variety of scenarios, some +represent very specific problems, while others are general purpose for bro= ad +classes of problem. Over time the error codes reported are liable to chang= e, +usually changing from a generic error to a more specific error. Thus +applications should be careful about checking for & taking action upon spe= cific +error codes, as their behaviour may change across releases. + +XML schemas +----------- + +The main objects exposed via the primary libvirt public API are usually +configured via XML documents following specific schemas. The XML schemas a= re +considered to be stable formats, whose compatibility will be maintained fo= rever. +Specific details are as follows: + +Attributes + Attributes defined on an XML element will never be removed or renamed. = New + attributes may be defined. If the set of valid values for an attribute = are + determined by an enumeration, the permitted values will never be remove= d or + renamed, only new values defined. None the less, specific hypervisors m= ay + reject usage of certain values according to their feature set. +Elements + Elements defined will never be removed or renamed. New child elements m= ay be + defined at any time. In places where only a single instance of a named = XML + element is used, future versions may be extended to permit multiple ins= tances + of the named XML element to be used. An element which currently has no + content may later gain child elements. + +Some hypervisor drivers may choose to allow use of hypervisor specific +extensions to the XML documents. These extensions will always be contained +within a hypervisor specific XML namespace. There is generally no guarante= e of +long term support for the hypervisor specific extensions across releases, = though +the project will endeavour to preserve them as long as is possible. Applic= ations +choosing to use hypervisor specific extensions should validate their opera= tion +against new libvirt or hypervisor releases. + +Configuration files +------------------- + +A number of programs / daemons provided libvirt rely on host filesystem +configuration files. These configuration files are accompanied by augeas l= ens +for easy manipulation by applications. There is in general no guarantee th= at +parameters available in the configuration file will be preserved across +releases, though the project will endeavour to preserve them as long as is +possible. If a configuration option is dropped from the file, the augeas l= ens +will retain the ability to read that configuration parameter, so that it i= s able +to read & update historically modified files. The default configuration fi= les +ship with all parameters commented out such that a deployment relies on the +built-in defaults of the application in question. There is no guarantee th= at the +defaults will remain the same across releases. A deployment that expects a +particular value for a configuration parameter should consider defining it +explicitly, instead of relying on the defaults. + +Hypervisor drivers +------------------ + +The libvirt project provides support for a wide variety of hypervisor driv= ers. +These drivers target certain versions of the hypervisor's underlying manag= ement +APIs. In general libvirt aims to work with any hypervisor version that is = still +broadly supported by its vendor. When a vendor discontinues support for a +particular hypervisor version it will be dropped by libvirt. Libvirt may c= hoose +to drop support for a particular hypervisor version prior to the vendor en= ding +support, if it deems that the likely usage is too small to justify the ong= oing +maintenance cost. + +Each hypervisor release will implement a distinct subset of features that = can be +expressed in the libvirt APIs and XML formats. While the XML schema syntax= will +be stable across releases, libvirt is unable to promise that it will alway= s be +able to support usage of the same features across hypervisor releases. Whe= re a +hypervisor changes the way a feature is implemented, the project will ende= avour +to adapt to the new implementation to provide the same semantics. In cases= where +the feature is discontinued by the hypervisor, libvirt will return an error +indicating it is not supported. Likewise libvirt will make reasonable effo= rts to +keep API calls working across hypervisor releases even if the underlying +implementation changes. In cases where this is impossible, a suitable erro= r will +be reported. The list of APIs which have implementations `is detailed +separately `__. + +RPC protocol +------------ + +For some hypervisor drivers, the libvirt.so library communicates with sepa= rate +libvirt daemons to perform work. This communication takes place over a bin= ary +RPC protocol defined by libvirt. The protocol uses the XDR format for data +encoding, and the message packet format is defined in libvirt source code. + +Applications are encouraged to use the primary libvirt.so library which +transparently talks to the daemons, so that they are not exposed to the +hypervisor driver specific details. None the less, the RPC protocol associ= ated +with the libvirtd is considered to be a long term stable ABI. It will only= ever +have new messages added to it, existing messages will not be removed, nor = have +their contents changed. Thus if an application does wish to provide its own +client side implementation of the RPC protocol this is supported, with the +caveat that the application will loose the ability to work with certain +hypervisors libvirt supports. The project reserves the right to define new +authentication and encryption options for the protocol, and the defaults u= sed in +this area may change over time. This is particularly true of the TLS ciphe= rs +permitted. Thus applications choosing to implement the RPC protocol must be +prepared to track support for new security options. If defaults are change= d, +however, it will generally be possible to reconfigure the daemon to use th= e old +defaults, albeit with possible implications for system security. + +Other daemons besides, libvirtd, also use the same RPC protocol, but with +different message types defined. These RPC protocols are all considered to= be +private implementations that are liable to change at any time. Application= s must +not attempt to talk to these other daemons directly. + +virsh client +------------ + +The virsh program provides a simple client to interact with an arbitrary l= ibvirt +hypervisor connection. Since it uses the primary public API of libvirt, it +should generally inherit the guarantees associated with that API, and with= the +hypervisor driver. The commands that virsh exposes, and the arguments they +accept are all considered to be long term stable. Existing commands and +arguments will not be removed or renamed. New commands and arguments may be +added in new releases. The text output format produced by virsh commands i= s not +generally guaranteed to be stable if it contains compound data (eg formatt= ed +tables or lists). Commands which output single data items (ie an object na= me, or +an XML document), can be treated as having stable format. --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668852; cv=none; d=zohomail.com; s=zohoarc; b=NMa1vdGxPeQqrogZZxSXkh5NOj88Z+CZNJGA417UcpngIGrzI1Ehd4yU3DlwuwxROM/Rbh+bFPc/yQTgo5C54zm1zfeXO6Qj2oNEWtZS4xl5ZnCfJcTE8Sls2AKm2CqSH/OSR4bgvj6+LEj6UdTYaG3C4b5jVdCYiHs7vzRdnWs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668852; 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=dRJTzigcIdl+iTvj9J2nxFNb08UsVRX5TGOYKxclF24=; b=ZDpSVrBEvX5bAmbwZcDVL3bZ056q2/hoJ0v5EuTCPpdAE1AjcMVV5kdAXVJ68k540omqKZ91pQgLUPNj1NUVdwP5pdmkxUbWdzNo65cLzzitXcO14rod3Yl0Aev9DWhjihNrbVKe7bwxbOpJ0v2ae/GCEu9JVjzeW6YGnxTtgkA= 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 1646668852962715.244842609809; Mon, 7 Mar 2022 08:00:52 -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-399-7WUff61pOS-mfi3mNottTA-1; Mon, 07 Mar 2022 11:00:23 -0500 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 75E451C05AF1; Mon, 7 Mar 2022 16:00:11 +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 58886400E408; Mon, 7 Mar 2022 16:00:11 +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 12511196BB81; Mon, 7 Mar 2022 16:00:11 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id AC13419305AE for ; Mon, 7 Mar 2022 16:00:08 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 805DA7D3CE; Mon, 7 Mar 2022 16:00:08 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id D38B58276B for ; Mon, 7 Mar 2022 16:00:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668852; 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=dRJTzigcIdl+iTvj9J2nxFNb08UsVRX5TGOYKxclF24=; b=FNUPEE6V6h6bMPd0Q+PQOgudJTuTtlVBQ5x6fWCyJIOkj3XXd+WvRJTRKPy19xyo9aZCgN Jj4dLTSHcKIbktXZzIIT8L11AE4Cdx530YzMJyYZrl2dn1nm9QThmZ46b7gVGH5OetVcW/ DkJOR1mxMLHZUJ1uY7RC7H1GrS4IScY= X-MC-Unique: 7WUff61pOS-mfi3mNottTA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 10/17] docs: Convert 'securityprocess' page to rST Date: Mon, 7 Mar 2022 16:59:30 +0100 Message-Id: <3701671e3fa842d9be3e1194f190467781f84106.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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.2 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: 1646668856100100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/meson.build | 2 +- docs/securityprocess.html.in | 119 ----------------------------------- docs/securityprocess.rst | 91 +++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 120 deletions(-) delete mode 100644 docs/securityprocess.html.in create mode 100644 docs/securityprocess.rst diff --git a/docs/meson.build b/docs/meson.build index b3432cc6f6..ab020ab090 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -61,7 +61,6 @@ docs_html_in_files =3D [ 'php', 'python', 'remote', - 'securityprocess', 'storage', 'testapi', 'testsuites', @@ -108,6 +107,7 @@ docs_rst_files =3D [ 'pci-addresses', 'platforms', 'programming-languages', + 'securityprocess', 'strategy', 'styleguide', 'submitting-patches', diff --git a/docs/securityprocess.html.in b/docs/securityprocess.html.in deleted file mode 100644 index 0e4802a1de..0000000000 --- a/docs/securityprocess.html.in +++ /dev/null @@ -1,119 +0,0 @@ - - - - - -

            Security Process

            - -
              - -

              - The libvirt project believes in responsible disclosure of - security problems, to allow vendors time to prepare and - distribute patches for problems ahead of their publication. - This page describes how the process works and how to report - potential security issues. -

              - -

              Reporting security issues

              - -

              - In the event that a bug in libvirt is found which is - believed to have (potential) security implications there - is a dedicated contact to which a bug report / notification - should be directed. Send an email with as many details of - the problem as possible (ideally with steps to reproduce) - to the following email address: -

              - - 
              -libvirt-security@redhat.com=
              - -

              - NB. while this email address is backed by a mailing list, it - is invitation only and moderated for non-members. As such you - will receive an auto-reply indicating the report is held for - moderation. Postings by non-members will be approved by a - moderator and the reporter copied on any replies. -

              - -

              Security notices

              - -

              - Information for all historical security issues is maintained in - machine parsable format in the - libvi= rt-security-notice GIT repository and - published online - in text, HTML and XML formats. Security notices are published - on the libvirt-an= nounce mailing list - when any embargo is lifted, or as soon as triaged if already - public knowledge. -

              - -

              Security team

              - -

              - The libvirt security team is made up of a subset of the libvirt - core development team which covers the various distro maintainers - of libvirt, along with nominated security engineers representing - the various vendors who distribute libvirt. The team is responsible - for analysing incoming reports from users to identify whether a - security problem exists and its severity. It then works to produce - a fix for all official stable branches of libvirt and coordinate - embargo dates between vendors to allow simultaneous release of the - fix by all affected parties. -

              - -

              - If you are a security representative of a vendor distributing - libvirt and would like to join the security team, send an email - to the afore-mentioned security address. Typically an existing - member of the security team will have to vouch for your credentials - before membership is approved. All members of the security team - are required to respect the embargo policy - described below. -

              - -

              Publication embargo policy

              - -

              - The libvirt security team operates a policy of - res= ponsible disclosure. - As such any security issue reported, that is not already publicly di= sclosed - elsewhere, will have an embargo date assigned. Members of the securi= ty team agree - not to publicly disclose any details of the security issue until the= embargo - date expires. -

              - -

              - The general aim of the team is to have embargo dates which - are two weeks or less in duration. If a problem is identified - with a proposed patch for a security issue, requiring further - investigation and bug fixing, the embargo clock may be restarted. - In exceptional circumstances longer initial embargoes may be - negotiated by mutual agreement between members of the security - team and other relevant parties to the problem. Any such extended - embargoes will aim to be at most one month in duration. -

              - - -

              CVE allocation

              - -

              - The libvirt security team will associate each security issue with - a CVE number. The CVE numbers will usually be allocated by one of - the vendor security engineers on the security team. -

              - -

              Branch fixing policy

              - -

              - The libvirt community maintains one or more stable release branches - at any given point in time. The security team will aim to publish - fixes for GIT master (which will become the next major release) and - each currently maintained stable release branch. The distro maintain= ers - will be responsible for backporting the officially published fixes to - other release branches where applicable. -

              - - diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst new file mode 100644 index 0000000000..adddbf76b0 --- /dev/null +++ b/docs/securityprocess.rst @@ -0,0 +1,91 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Security Process +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +The libvirt project believes in responsible disclosure of security problem= s, to +allow vendors time to prepare and distribute patches for problems ahead of= their +publication. This page describes how the process works and how to report +potential security issues. + +Reporting security issues +------------------------- + +In the event that a bug in libvirt is found which is believed to have +(potential) security implications there is a dedicated contact to which a = bug +report / notification should be directed. Send an email with as many detai= ls of +the problem as possible (ideally with steps to reproduce) to the following= email +address: + +:: + + libvirt-security@redhat.com + +NB. while this email address is backed by a mailing list, it is invitation= only +and moderated for non-members. As such you will receive an auto-reply indi= cating +the report is held for moderation. Postings by non-members will be approve= d by a +moderator and the reporter copied on any replies. + +Security notices +---------------- + +Information for all historical security issues is maintained in machine pa= rsable +format in the `libvirt-security-notice GIT +repository `__ and +`published online `__ in text, HTML and XML +formats. Security notices are published on the `libvirt-announce mailing +list `__ when any embargo is lifte= d, or +as soon as triaged if already public knowledge. + +Security team +------------- + +The libvirt security team is made up of a subset of the libvirt core devel= opment +team which covers the various distro maintainers of libvirt, along with +nominated security engineers representing the various vendors who distribu= te +libvirt. The team is responsible for analysing incoming reports from users= to +identify whether a security problem exists and its severity. It then works= to +produce a fix for all official stable branches of libvirt and coordinate e= mbargo +dates between vendors to allow simultaneous release of the fix by all affe= cted +parties. + +If you are a security representative of a vendor distributing libvirt and = would +like to join the security team, send an email to the afore-mentioned secur= ity +address. Typically an existing member of the security team will have to vo= uch +for your credentials before membership is approved. All members of the sec= urity +team are **required to respect the embargo policy** described below. + +Publication embargo policy +-------------------------- + +The libvirt security team operates a policy of `responsible +disclosure `__. As s= uch +any security issue reported, that is not already publicly disclosed elsewh= ere, +will have an embargo date assigned. Members of the security team agree not= to +publicly disclose any details of the security issue until the embargo date +expires. + +The general aim of the team is to have embargo dates which are two weeks o= r less +in duration. If a problem is identified with a proposed patch for a securi= ty +issue, requiring further investigation and bug fixing, the embargo clock m= ay be +restarted. In exceptional circumstances longer initial embargoes may be +negotiated by mutual agreement between members of the security team and ot= her +relevant parties to the problem. Any such extended embargoes will aim to b= e at +most one month in duration. + +CVE allocation +-------------- + +The libvirt security team will associate each security issue with a CVE nu= mber. +The CVE numbers will usually be allocated by one of the vendor security +engineers on the security team. + +Branch fixing policy +-------------------- + +The libvirt community maintains one or more stable release branches at any= given +point in time. The security team will aim to publish fixes for GIT master = (which +will become the next major release) and each currently maintained stable r= elease +branch. The distro maintainers will be responsible for backporting the +officially published fixes to other release branches where applicable. --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668868; cv=none; d=zohomail.com; s=zohoarc; b=A8AbhDPRpaq+3/Tk8joZ+04u9oMqoyJf6Noj6q3jZ4eJAOIC4CqW2zs2Dy/ijSUFBRYJPatswPXazM8UySKOvFHRo9VvDWAZvLW6lY0tnKf+8NagAhKYxkzDVjI0ewPeoJKgKRJD+9R7z1nmSWSac5uR711v3p+M2G2XPYt1zu4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668868; 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=z0vXhL2Ee+DoP5MTvqiF9oPLH7edqp7TarXEsaKO8ls=; b=WWcf06ze17dEKp0DfqClkC/TdhxPR4t1Mt7w8MeNMCCvV5IPF1qqIP8/TPe7O+v993Qu7FdCIULN8Na7zA+t1yhDjeiiDJiphqzRSTy3D2jIfHKchlCSsFiqFuoQSSlGYHbq+o6j+C0Gw9/h6R4nNrD3VC03xKd9gl4AWtaQXUg= 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 1646668868544870.0477876144145; Mon, 7 Mar 2022 08:01:08 -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-499-mSm_25TlMJOwMi5QcuUblA-1; Mon, 07 Mar 2022 11:00:40 -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 52131804BD8; Mon, 7 Mar 2022 16:00:25 +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 39715C23DB1; Mon, 7 Mar 2022 16:00:25 +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 1C32E196BB89; Mon, 7 Mar 2022 16:00:25 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id BD1CE19305AE for ; Mon, 7 Mar 2022 16:00:09 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 8BD997D3CE; Mon, 7 Mar 2022 16:00:09 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id E4D1E82767 for ; Mon, 7 Mar 2022 16:00:08 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668867; 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=z0vXhL2Ee+DoP5MTvqiF9oPLH7edqp7TarXEsaKO8ls=; b=iGHtvhXAt+ONqq9Sm28KoQtUyjpLEA9Jbue4pCGvjBX+NNNaTsECflstkRvTeNWmvn3sbl BVkGl1Oi93OLewJXR/4ujA5IIoRzWlL2OKt0FJ+B4zfs1h+8aXaLuhB8OiS8gM6dusWaUx R8u3EwPq7ama7AIDUMceDB2dzNXlFME= X-MC-Unique: mSm_25TlMJOwMi5QcuUblA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 11/17] docs: securityprocess: Don't claim that we have maint branches Date: Mon, 7 Mar 2022 16:59:31 +0100 Message-Id: <65afcd14225b0b5be8cfeb1a20247f674a69a09e.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668869686100003 Content-Type: text/plain; charset="utf-8" The 'Branch fixing policy' paragraph claims that we have at least one actively maintained stable branch which isn't currently the case. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/securityprocess.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst index adddbf76b0..e1dc626f68 100644 --- a/docs/securityprocess.rst +++ b/docs/securityprocess.rst @@ -84,8 +84,8 @@ engineers on the security team. Branch fixing policy -------------------- -The libvirt community maintains one or more stable release branches at any= given -point in time. The security team will aim to publish fixes for GIT master = (which -will become the next major release) and each currently maintained stable r= elease -branch. The distro maintainers will be responsible for backporting the -officially published fixes to other release branches where applicable. +The security team will aim to publish fixes for GIT master (which will bec= ome +the next major release) and each currently maintained stable release branc= h, if +there's any. +The distro maintainers will be responsible for backporting the officially +published fixes to other release branches where applicable. --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668842; cv=none; d=zohomail.com; s=zohoarc; b=SgLq5F3iCWvyk2+ptZWBM8quoUorUbWSRxRJuGLsOlQqbUmpOoe/gu79riI6lzbnvfg2rWzPAiqsNmlPaJet7Ybgk0KzVxpiuYi/7pMn7cog1nCdXjDv93QgVGcyyhzoOopbTq3Xa4d46wqcPJdTFUmFUYPH6ZOLWMkVpIDEpSc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668842; 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=QYPeR9QBY3xCFDor0wgmfkfiRVmnP2EuUUS+63ZW/gw=; b=LykWeuiSo5WXd8SvaDpfHpIplO5bz4wdjdONmiUNcxFkVqZlc4hpOSA8fMMk1Yx8+8tVXexZ3zcbHPlFRN6UCoAFF1fD/q3T8fsNpXeXyrpZ7knxoMAQ343ZdgPzBjpt57MV92AZgUZBhvpDYy0kkh8jgU0hRLwPMaqcthXcCnY= 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 1646668842784570.3831525760368; Mon, 7 Mar 2022 08:00:42 -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-195-P2oZfu6FMsCJqSY6Xm4qnQ-1; Mon, 07 Mar 2022 11:00:37 -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 1692E1C05152; Mon, 7 Mar 2022 16:00:13 +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 EF51E145FBAE; Mon, 7 Mar 2022 16:00:12 +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 C4C90196BB91; Mon, 7 Mar 2022 16:00:12 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id D267019305AF for ; Mon, 7 Mar 2022 16:00:10 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id A3F817D3CE; Mon, 7 Mar 2022 16:00:10 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0B00C82767 for ; Mon, 7 Mar 2022 16:00:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668841; 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=QYPeR9QBY3xCFDor0wgmfkfiRVmnP2EuUUS+63ZW/gw=; b=Oqwkv6brjYuo2ICU+MwFomiqOCjiQjwv2QKsrGHooe+6NmO/oTtvA5/KWdhhczxassgX83 Fi3op3QA89prTA2kGG6h6bDRi3jdcQbniBb9ECj9UMTl8fh848YxhD9ygwxvFSMRzXak+5 qftfk1DjPzjj8Y03H28Il1XPjpN4LYI= X-MC-Unique: P2oZfu6FMsCJqSY6Xm4qnQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 12/17] docs: Convert 'governance' page to rST Date: Mon, 7 Mar 2022 16:59:32 +0100 Message-Id: <41354fd91c3cdf2d44d372d7c12020f17b0207be.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668844574100004 Content-Type: text/plain; charset="utf-8" Extra care is taken to preserve the 'codeofconduct' anchor which is used in our page template. Upcoming patch will change that but we'll retain the anchor. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/governance.html.in | 298 ---------------------------------------- docs/governance.rst | 232 +++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 233 insertions(+), 299 deletions(-) delete mode 100644 docs/governance.html.in create mode 100644 docs/governance.rst diff --git a/docs/governance.html.in b/docs/governance.html.in deleted file mode 100644 index 61ab52c858..0000000000 --- a/docs/governance.html.in +++ /dev/null @@ -1,298 +0,0 @@ - - - - -

              Project governance

              - -
                - -

                - The libvirt project operates as a meritocratic, consensus-based comm= unity. - Anyone with an interest in the project can join the community, contr= ibuting - to the ongoing development of the project's work. This pages describ= es how - that participation takes place and how contributors earn merit, and = thus - influence, within the community. -

                - -

                Code of conduct

                - -

                - The libvirt project community covers people from a wide variety of - countries, backgrounds and positions. This global diversity is a gre= at - strength of the project, but can also lead to communication issues, - which may in turn cause unhappiness. To maximise happiness of the - project community taken as a whole, all members (whether users, - contributors or committers) are expected to abide by the project's - code of conduct. At a high level the code can be summarized as - "be excellent to each other". Expanding on this: -

                - -
                  -
                • Be respectful: disagreements between people are= to - be expected and are usually the sign of healthy debate and engagem= ent. - Disagreements can lead to frustration and even anger for some memb= ers. - Turning to personal insults, intimidation or threatening behaviour= does - not improve the situation though. Participants should thus take ca= re to - ensure all communications / interactions stay professional at all = times.
                  • - -
                • Be considerate: remember that the community has= members - with a diverse background many of whom have English as a second la= nguage. - What might appear impolite, may simply be a result of a lack of kn= owledge - of the English language. Bear in mind that actions will have an im= pact - on other community members and the project as a whole, so take pot= ential - consequences into account before pursuing a course of action.
                  • - -
                • Be forgiving: humans are fallible and as such p= rone - to make mistakes and inexplicably change their positions at times.= Don't - assume that other members are acting with malicious intent. Be pre= pared - to forgive people who make mistakes and assist each other in learn= ing - from them. Playing a blame game doesn't help anyone.
                  • -
                - -

                Roles and responsibilities

                - -

                Users

                - -

                - The users are anyone who has a need for the output of the project. - There are no rules or requirements to become a user of libvirt. Even - if the software does not yet work on their OS platform, a person can - be considered a potential future user and welcomed to participate. -

                - -

                - Participation by users is key to ensuring the project moves in the - right direction, satisfying their real world needs. Users are - encouraged to participate in the broader libvirt community in any - number of ways: -

                - -
                  -
                • Evangelism: spread the word about what libvirt is doing, how it - helps solve your problems. This can be via blog articles, social - media postings, video blogs, user group / conference presentations - and any other method of disseminating information
                  • -
                • Feedback: let the developers know about what does and does not - work with the project. Talk to developers on the project's - IRC channel and mailing list, or find them at conferences. Tell - them what gaps the project has or where they should look for - future development
                  • -
                • Moral support: developers live for recognition of the positive - impact their work has on users' lives. Give thanks to the develope= rs - when evangelising the project, or when meeting them at user groups, - conferences, etc.
                  • -
                - -

                - The above is not an exhaustive list of things users can do to - participate in the project. Further ideas and suggestions are - welcome. Users are encouraged to take their participation - further and become contributors to the project in any of the - ways listed in the next section. -

                - -

                Contributors

                - -

                - The contributors are community members who have some concrete impact - to the ongoing development of the project. There are many ways in wh= ich - members can contribute, with no requirement to be a software enginee= r. - Many users can in fact consider themselves contributors merely by - engaging in evangelism for the project. -

                - -
                  -
                • Bug reporting: improve the quality of the project by reporting - any problems found either to the project's own bug tracker, or to - that of the OS vendor shipping the libvirt code.
                  • -
                • User help: join the IRC channel or mail= ing list - to assist or advice other users in troubleshooting the problems th= ey face.
                  • -
                • Feature requests: help set the direction for future work by - reporting details of features which are missing to the project's - own bug tracker or mailing lists.
                  • -
                • Graphical design: contribute to the development of the project's - websites / wiki brand with improved graphics, styling or layout. -
                • Code development: write and submit patches to address bugs or im= plement - new features
                  • -
                • Architectural design: improve the usefulness of the project - by providing feedback on the design of proposed features, to - ensure they satisfy the broadest applicable needs and survive - the long term
                  • -
                • Code review: look at patches which are submitted and critique - the code to identify bugs, potential design problems or other - issues which should be addressed before the code is accepted
                  • -
                • Documentation: contribute to content on personal blogs, the - website, wiki, code comments, or any of the formal documentation - efforts.
                  • -
                • Translation: join the Fedora transifex community to improve the - quality of translations needed by the libvirt project.
                  • -
                • Testing: try proposed patches or release candidates and report - whether the build passes and the changes work as expected.
                  • -
                - -

                - The above is not an exhaustive list of things members can do to - contribute to the project. Further ideas and suggestions are - welcome. -

                - -

                - There are no special requirements to becoming a contributor other - than having the interest and ability to provide a contribution. The - libvirt project does not require any - "Contributor License Agreement" - to be signed prior to engagement with the community. However for - contributing patches, providing a 'Signed-off-by' line with the - author's legal name and e-mail address to demonstrate agreement - and compliance with the - Developer Certificate of Origin is required. -

                - -

                - In making a non-patch contribution to the project, the community - member is implicitly stating that they accept the terms of the licen= se - under which the work they are contributing to is distributed. They a= re - also implicitly stating that they have the legal right to make the - contribution, if doing so on behalf of a broader organization / - company. Most of the project's code is distributed under the GNU - Lesser General Public License, version 2.1 or later. Details of the - exact license under which contributions will be presumed to be - covered are found in the source repositories, or website in question. -

                - -

                Committers

                - -

                - The committers are the subset of contributors who have direct access - to commit code to the project's primary source code repositories, wh= ich - are currently using the GIT software. The committers are chosen based - on the quality of their contributions over a period of time. This in= cludes - both the quality of code they submit, as well as the quality of revi= ews - they provide on other contributors' submissions and a demonstration = that - they understand day-to-day operation of the project and its goals. T= here - is no minimum level of contribution required in order to become a co= mmitter, - though 2-3 months worth of quality contribution would be a rough gui= de. -

                - -

                - There are no special requirements to becoming a committer other than= to - have shown a willingness and ability to contribute to the project ov= er - an extended period of time. Proposals for elevating contributors to - committers are typically made by existing committers, though contrib= utors - are also welcome to make proposals. The decision to approve the elev= ation - of a contributor to a committer is made through "rough consensus" be= tween - the existing committers. -

                - -

                - The aim in elevating contributors to committers is to ensure that th= ere - is a broad base of experience and expertize across all areas of the - project's work. Committers are not required to have knowledge across - all areas of the project's work. While an approved committer has the - technical ability to commit code to any area of the project, by conv= ention - they will only commit to areas they feel themselves to be qualified = to - evaluate the contribution. If in doubt, committers will defer to the - opinion of other committers with greater expertize in an area. -

                - -

                - The committers hold the ultimate control over what contributions are - accepted by the project, however, this does not mean they have the - right to do whatever they want. Where there is debate and disagreeme= nt - between contributors, committers are expected to look at the issues = with - an unbiased point of view and help achieve a "rough consensus". If t= he - committer has a conflict of interest in the discussion, for example = due - to their position of employment, they are expected to put the needs = of - the community project first. If they cannot put the community project - first, they must declare their conflict of interest, and allow other - non-conflicted committers to make any final decision. -

                - -

                - The committers are expected to monitor contributions to areas of the - project where they have expertize and ensure that either some form of - feedback is provided to the contributor, or to accept their contribu= tion. - There is no formal minimum level of approval required to accept a - contribution. Positive review by any committer experienced in the ar= ea - of work is considered to be enough to justify acceptance in normal - circumstances. Where one committer explicitly rejects a contribution, - however, other committers should not override that rejection without - first establishing a "rough consensus" amongst the broader group of - committers. -

                - -

                - Being a committer is a privilege, not a right. In exceptional - circumstances, the privilege may be removed from an active - contributor. Such decisions will be taken based on "rough - consensus" amongst other committers. In the event that a committer - is no longer able to participate in the project, after some period - of inactivity passes, they may be asked to confirm that they wish - to retain their role as a committer. -

                - -

                Security team

                - -

                - The security team consists of a subset of the project committers - along with representatives from vendors shipping the project's - software. The subset of project committers is chosen to be the - minimal size necessary to provide expertise spanning most of - the project's work. Further project committers may be requested - to engage in resolving specific security issues on a case by - case basis. Any vendor who is shipping the project's software - may submit a request for one or more of their representatives - to join the security team. Such requests must by approved by - existing members of the team vouching for the integrity of - the nominated person or organization. -

                - -

                - Members of the security team are responsible for triaging and - resolving any security issues that are reported to the project. - They are expected to abide by the project's documented - security process. In particular - they must respect any embargo period agreed amongst the team - before disclosing a private issue. -

                - -

                Rough consensus

                - -

                - A core concept for governance of the project described above is - that of "rough consensus". To expand on this, it is a process - of decision making that involves the following steps -

                - -
                  -
                • Proposal
                  • -
                • Discussion
                  • -
                • Vote (exceptional circumstances only)
                  • -
                • Decision
                  • -
                - -

                - To put this into words, any contributor is welcome to make a proposal - for consideration. Any contributor may participate in the discussions - around the proposal. The discussion will usually result in agreement - between the interested parties, or at least agreement between the - committers. Only in the very exceptional circumstance where there - is disagreement between committers, would a vote be considered. - Even in these exceptional circumstances, it is usually found to be - obvious what the majority opinion of the committers is. In the event - that even a formal vote is tied, the committers will have to hold - ongoing discussions until the stalemate is resolved or the proposal - withdrawn. -

                - -

                - The overall goal of the "rough consensus" process is to ensure that - decisions can be made within the project, with a minimum level of - bureaucracy and process. Implicit in this is that any person who does - not explicitly reject to a proposal is assumed to be supportive, or - at least agnostic. -

                - - - - diff --git a/docs/governance.rst b/docs/governance.rst new file mode 100644 index 0000000000..df90ce678d --- /dev/null +++ b/docs/governance.rst @@ -0,0 +1,232 @@ +.. role:: anchor(raw) + :format: html + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Project governance +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +The libvirt project operates as a meritocratic, consensus-based community. +Anyone with an interest in the project can join the community, contributin= g to +the ongoing development of the project's work. This pages describes how th= at +participation takes place and how contributors earn merit, and thus influe= nce, +within the community. + +:anchor:`` + +Code of conduct +--------------- + +The libvirt project community covers people from a wide variety of countri= es, +backgrounds and positions. This global diversity is a great strength of the +project, but can also lead to communication issues, which may in turn cause +unhappiness. To maximise happiness of the project community taken as a who= le, +all members (whether users, contributors or committers) are expected to ab= ide by +the project's code of conduct. At a high level the code can be summarized = as +*"be excellent to each other"*. Expanding on this: + +- **Be respectful:** disagreements between people are to be expected and = are + usually the sign of healthy debate and engagement. Disagreements can le= ad to + frustration and even anger for some members. Turning to personal insult= s, + intimidation or threatening behaviour does not improve the situation th= ough. + Participants should thus take care to ensure all communications / + interactions stay professional at all times. +- **Be considerate:** remember that the community has members with a dive= rse + background many of whom have English as a second language. What might a= ppear + impolite, may simply be a result of a lack of knowledge of the English + language. Bear in mind that actions will have an impact on other commun= ity + members and the project as a whole, so take potential consequences into + account before pursuing a course of action. +- **Be forgiving:** humans are fallible and as such prone to make mistake= s and + inexplicably change their positions at times. Don't assume that other m= embers + are acting with malicious intent. Be prepared to forgive people who make + mistakes and assist each other in learning from them. Playing a blame g= ame + doesn't help anyone. + +Roles and responsibilities +-------------------------- + +Users +~~~~~ + +The users are anyone who has a need for the output of the project. There a= re no +rules or requirements to become a user of libvirt. Even if the software do= es not +yet work on their OS platform, a person can be considered a potential futu= re +user and welcomed to participate. + +Participation by users is key to ensuring the project moves in the right +direction, satisfying their real world needs. Users are encouraged to +participate in the broader libvirt community in any number of ways: + +- Evangelism: spread the word about what libvirt is doing, how it helps s= olve + your problems. This can be via blog articles, social media postings, vi= deo + blogs, user group / conference presentations and any other method of + disseminating information +- Feedback: let the developers know about what does and does not work wit= h the + project. Talk to developers on the project's IRC channel and mailing li= st, or + find them at conferences. Tell them what gaps the project has or where = they + should look for future development +- Moral support: developers live for recognition of the positive impact t= heir + work has on users' lives. Give thanks to the developers when evangelisi= ng the + project, or when meeting them at user groups, conferences, etc. + +The above is not an exhaustive list of things users can do to participate = in the +project. Further ideas and suggestions are welcome. Users are encouraged t= o take +their participation further and become contributors to the project in any = of the +ways listed in the next section. + +Contributors +~~~~~~~~~~~~ + +The contributors are community members who have some concrete impact to the +ongoing development of the project. There are many ways in which members c= an +contribute, with no requirement to be a software engineer. Many users can = in +fact consider themselves contributors merely by engaging in evangelism for= the +project. + +- Bug reporting: improve the quality of the project by reporting any prob= lems + found either to the project's own bug tracker, or to that of the OS ven= dor + shipping the libvirt code. +- User help: join the `IRC channel or mailing list `__ to a= ssist + or advice other users in troubleshooting the problems they face. +- Feature requests: help set the direction for future work by reporting d= etails + of features which are missing to the project's own bug tracker or maili= ng + lists. +- Graphical design: contribute to the development of the project's websit= es / + wiki brand with improved graphics, styling or layout. +- Code development: write and submit patches to address bugs or implement= new + features +- Architectural design: improve the usefulness of the project by providing + feedback on the design of proposed features, to ensure they satisfy the + broadest applicable needs and survive the long term +- Code review: look at patches which are submitted and critique the code = to + identify bugs, potential design problems or other issues which should be + addressed before the code is accepted +- Documentation: contribute to content on personal blogs, the website, wi= ki, + code comments, or any of the formal documentation efforts. +- Translation: join the Fedora transifex community to improve the quality= of + translations needed by the libvirt project. +- Testing: try proposed patches or release candidates and report whether = the + build passes and the changes work as expected. + +The above is not an exhaustive list of things members can do to contribute= to +the project. Further ideas and suggestions are welcome. + +There are no special requirements to becoming a contributor other than hav= ing +the interest and ability to provide a contribution. The libvirt project **= does +not require** any *"Contributor License Agreement"* to be signed prior to +engagement with the community. However for contributing patches, providing= a +'Signed-off-by' line with the author's legal name and e-mail address to +demonstrate agreement and compliance with the `Developer Certificate of +Origin `__ is required. + +In making a non-patch contribution to the project, the community member is +implicitly stating that they accept the terms of the license under which t= he +work they are contributing to is distributed. They are also implicitly sta= ting +that they have the legal right to make the contribution, if doing so on be= half +of a broader organization / company. Most of the project's code is distrib= uted +under the GNU Lesser General Public License, version 2.1 or later. Details= of +the exact license under which contributions will be presumed to be covered= are +found in the source repositories, or website in question. + +Committers +~~~~~~~~~~ + +The committers are the subset of contributors who have direct access to co= mmit +code to the project's primary source code repositories, which are currently +using the GIT software. The committers are chosen based on the quality of = their +contributions over a period of time. This includes both the quality of cod= e they +submit, as well as the quality of reviews they provide on other contributo= rs' +submissions and a demonstration that they understand day-to-day operation = of the +project and its goals. There is no minimum level of contribution required = in +order to become a committer, though 2-3 months worth of quality contributi= on +would be a rough guide. + +There are no special requirements to becoming a committer other than to ha= ve +shown a willingness and ability to contribute to the project over an exten= ded +period of time. Proposals for elevating contributors to committers are typ= ically +made by existing committers, though contributors are also welcome to make +proposals. The decision to approve the elevation of a contributor to a com= mitter +is made through "rough consensus" between the existing committers. + +The aim in elevating contributors to committers is to ensure that there is= a +broad base of experience and expertize across all areas of the project's w= ork. +Committers are not required to have knowledge across all areas of the proj= ect's +work. While an approved committer has the technical ability to commit code= to +any area of the project, by convention they will only commit to areas they= feel +themselves to be qualified to evaluate the contribution. If in doubt, comm= itters +will defer to the opinion of other committers with greater expertize in an= area. + +The committers hold the ultimate control over what contributions are accep= ted by +the project, however, this does not mean they have the right to do whateve= r they +want. Where there is debate and disagreement between contributors, committ= ers +are expected to look at the issues with an unbiased point of view and help +achieve a "rough consensus". If the committer has a conflict of interest i= n the +discussion, for example due to their position of employment, they are expe= cted +to put the needs of the community project first. If they cannot put the +community project first, they must declare their conflict of interest, and= allow +other non-conflicted committers to make any final decision. + +The committers are expected to monitor contributions to areas of the proje= ct +where they have expertize and ensure that either some form of feedback is +provided to the contributor, or to accept their contribution. There is no = formal +minimum level of approval required to accept a contribution. Positive revi= ew by +any committer experienced in the area of work is considered to be enough to +justify acceptance in normal circumstances. Where one committer explicitly +rejects a contribution, however, other committers should not override that +rejection without first establishing a "rough consensus" amongst the broad= er +group of committers. + +Being a committer is a privilege, not a right. In exceptional circumstance= s, the +privilege may be removed from an active contributor. Such decisions will be +taken based on "rough consensus" amongst other committers. In the event th= at a +committer is no longer able to participate in the project, after some peri= od of +inactivity passes, they may be asked to confirm that they wish to retain t= heir +role as a committer. + +Security team +~~~~~~~~~~~~~ + +The security team consists of a subset of the project committers along with +representatives from vendors shipping the project's software. The subset of +project committers is chosen to be the minimal size necessary to provide +expertise spanning most of the project's work. Further project committers = may be +requested to engage in resolving specific security issues on a case by case +basis. Any vendor who is shipping the project's software may submit a requ= est +for one or more of their representatives to join the security team. Such +requests must by approved by existing members of the team vouching for the +integrity of the nominated person or organization. + +Members of the security team are responsible for triaging and resolving any +security issues that are reported to the project. They are expected to abi= de by +the project's documented `security process `__. In +particular they must respect any embargo period agreed amongst the team be= fore +disclosing a private issue. + +Rough consensus +--------------- + +A core concept for governance of the project described above is that of "r= ough +consensus". To expand on this, it is a process of decision making that inv= olves +the following steps + +- Proposal +- Discussion +- Vote (exceptional circumstances only) +- Decision + +To put this into words, any contributor is welcome to make a proposal for +consideration. Any contributor may participate in the discussions around t= he +proposal. The discussion will usually result in agreement between the inte= rested +parties, or at least agreement between the committers. Only in the very +exceptional circumstance where there is disagreement between committers, w= ould a +vote be considered. Even in these exceptional circumstances, it is usually= found +to be obvious what the majority opinion of the committers is. In the event= that +even a formal vote is tied, the committers will have to hold ongoing discu= ssions +until the stalemate is resolved or the proposal withdrawn. + +The overall goal of the "rough consensus" process is to ensure that decisi= ons +can be made within the project, with a minimum level of bureaucracy and pr= ocess. +Implicit in this is that any person who does not explicitly reject to a pr= oposal +is assumed to be supportive, or at least agnostic. diff --git a/docs/meson.build b/docs/meson.build index ab020ab090..08c324a74b 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -50,7 +50,6 @@ docs_html_in_files =3D [ 'formatsecret', 'formatstoragecaps', 'formatstorageencryption', - 'governance', 'hooks', 'index', 'internals', @@ -98,6 +97,7 @@ docs_rst_files =3D [ 'formatstorage', 'glib-adoption', 'goals', + 'governance', 'hacking', 'libvirt-go', 'libvirt-go-xml', --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668867; cv=none; d=zohomail.com; s=zohoarc; b=UFhhdo4QlrJEDDqgedipH84N9/uViXI1QhB6JlI/y2Ykpje010NCRvkCy2dM1Ajr5+HIVkqEmAK55A2lg3XTgIB26Eg7dm6mAjHR02A0XEpmiX551+36EHXGUXNvJ6LuCm18Fo2a7qv0M07+/oWAHrQCXP+Lr5A330sc2rq4UMI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668867; 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=lB0qrvDrBR5fcfuNkcpN8c8So5hbZg3cWS21VepA9ug=; b=RsuqsmpQs9Ye2dIOCfYYh0Cloed5uf74vTdjcysSvltslQYHc11TQ8DL2MjlvAiscE6aQibppQDjSdzzsEKjdFZkqvyoruMeuJp3Hhc93nOGQVJHmHl3p0qglHNEAqfXT/9XnFJJfagyQ84bghmCpEeHl1S0FnvY0KD+W0uKt7I= 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 1646668867329410.61560538753895; Mon, 7 Mar 2022 08:01:07 -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-536-x5icS3OnNuGkQJ6DvbiudQ-1; Mon, 07 Mar 2022 11:00:34 -0500 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 6FE70185A7A4; Mon, 7 Mar 2022 16:00:16 +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 51B5240C1247; Mon, 7 Mar 2022 16:00:16 +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 1B8F319305AF; Mon, 7 Mar 2022 16:00:16 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id EACB119305AE for ; Mon, 7 Mar 2022 16:00:11 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id BD9F97DE5E; Mon, 7 Mar 2022 16:00:11 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 108F77D3CE for ; Mon, 7 Mar 2022 16:00:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668865; 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=lB0qrvDrBR5fcfuNkcpN8c8So5hbZg3cWS21VepA9ug=; b=HDA0mxyqvBAN2M1SQVI7JKQWPTmhNBQ5cfq+4sTui3js6c2d3AFxhxVGQZUMitKgxXUYKH 5jKvceJzfKaWtBRCuMKEYDNlhOuIpdNvkWZkY7Wq/yS8KcTfKzznZWhSPhrsIsO2fmINen 1wAoMGmPxeEM2h6MWOdBq9442O7bEKY= X-MC-Unique: x5icS3OnNuGkQJ6DvbiudQ-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 13/17] docs: page.xsl: Update anchor to the 'Code of conduct' paragraph Date: Mon, 7 Mar 2022 16:59:33 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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.2 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: 1646668867844100001 Content-Type: text/plain; charset="utf-8" Use the anchor name as generated by rst2html. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/page.xsl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/page.xsl b/docs/page.xsl index 72a6fa0842..a6a270896c 100644 --- a/docs/page.xsl +++ b/docs/page.xsl @@ -187,7 +187,7 @@
                --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668927; cv=none; d=zohomail.com; s=zohoarc; b=Qes3SdGQ9CMka5EvsQLnUny0slUDqNoYq4ahYXI4fw8G1Fiqr6XAa1v1GUYtBeE6GiN1muEBmo2bjkPUav/BFb/568pIuzoSgGVjImDLtCHS+/PAAoC1QU6p+p6+P6+cIaUoNqbGoEmPxsQGXAY6Lt1+P7ZTXeDEqa3FBPIr9zE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668927; 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=fE7b54ZsGW0c949qdhTMK7o9gfEok6Ryxe41tsClk9A=; b=X8ZxwzSOsLgRi6yvNa6fzI5eK1iLzTG2d6YaSidkkuIKbsmOiVHdVZ5nwkoIS68ojEDkYeAOkZjCLk20ux/Dc2JaDuGavAO6wbzaxghB1Xp4K6D5+8LRNGJQ6Fxfy9jFR5c5qmz2HmS1ZuWH9iOr3+y0IBoC37M/jxcVc7U2ljQ= 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 1646668927371932.7563902693335; Mon, 7 Mar 2022 08:02:07 -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-648-yR7wyYN-N7OVKNZfjC5wUg-1; Mon, 07 Mar 2022 11:00:46 -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 0DD5C104989B; Mon, 7 Mar 2022 16:00:26 +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 EBEBDC08096; Mon, 7 Mar 2022 16:00:25 +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 5E395196BB83; Mon, 7 Mar 2022 16:00:25 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 1BBA3196BB83 for ; Mon, 7 Mar 2022 16:00:13 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id CC40D82764; Mon, 7 Mar 2022 16:00:12 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 347067D3CE for ; Mon, 7 Mar 2022 16:00:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668926; 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=fE7b54ZsGW0c949qdhTMK7o9gfEok6Ryxe41tsClk9A=; b=aQ1sMwRVr3VdiXKEK9eVJly+sH7NvHY4oiWYihg3W+rx7QyVWco4SkhkksZFIJMbptiBLM S96KfewbZl4sRBqtQH4hnco/iQGzOWxiq4d39P7Q3UBk08Un6MwHIbQtpLB+Tv0sPJuMIL cvbRyQoQmO+/8vGG+JUKh+XjgwcAwaI= X-MC-Unique: yR7wyYN-N7OVKNZfjC5wUg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 14/17] docs: Convert 'drivers' page to rST Date: Mon, 7 Mar 2022 16:59:34 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668928483100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa --- docs/drivers.html.in | 44 -------------------------------------------- docs/drivers.rst | 31 +++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 32 insertions(+), 45 deletions(-) delete mode 100644 docs/drivers.html.in create mode 100644 docs/drivers.rst diff --git a/docs/drivers.html.in b/docs/drivers.html.in deleted file mode 100644 index 824604998e..0000000000 --- a/docs/drivers.html.in +++ /dev/null @@ -1,44 +0,0 @@ - - - - -

                Internal drivers

                - - - -

                - The libvirt public API delegates its implementation to one or - more internal drivers, depending on the connect= ion URI - passed when initializing the library. There is always a hypervisor d= river - active, and if the libvirt daemon is available there will usually be= a - network and storage driver active. -

                - -

                Hypervisor drivers

                - -

                - The hypervisor drivers currently supported by libvirt are: -

                - - - - - diff --git a/docs/drivers.rst b/docs/drivers.rst new file mode 100644 index 0000000000..b72266e876 --- /dev/null +++ b/docs/drivers.rst @@ -0,0 +1,31 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Internal drivers +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +- `Hypervisor drivers <#hypervisor-drivers>`__ +- `Storage drivers `__ +- `Node device driver `__ +- `Secret driver `__ + +The libvirt public API delegates its implementation to one or more internal +drivers, depending on the `connection URI `__ passed when initia= lizing +the library. There is always a hypervisor driver active, and if the libvirt +daemon is available there will usually be a network and storage driver act= ive. + +Hypervisor drivers +------------------ + +The hypervisor drivers currently supported by libvirt are: + +- `LXC `__ - Linux Containers +- `OpenVZ `__ +- `QEMU `__ +- `Test `__ - Used for testing +- `VirtualBox `__ +- `VMware ESX `__ +- `VMware Workstation/Player `__ +- `Xen `__ +- `Microsoft Hyper-V `__ +- `Virtuozzo `__ +- `Bhyve `__ - The BSD Hypervisor +- `Cloud Hypervisor `__ diff --git a/docs/meson.build b/docs/meson.build index 08c324a74b..fce6533301 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -25,7 +25,6 @@ docs_html_in_files =3D [ 'dbus', 'docs', 'downloads', - 'drivers', 'drvbhyve', 'drvesx', 'drvhyperv', @@ -87,6 +86,7 @@ docs_rst_files =3D [ 'contribute', 'daemons', 'developer-tooling', + 'drivers', 'drvqemu', 'drvch', 'errors', --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668895; cv=none; d=zohomail.com; s=zohoarc; b=ZIck7jix4ovxsyr2HLrgWjMdNZD77T3CMKXdOCVtZvF3n2YDG/1IwIl3bc/PtOIF1xk78EAXttD43qUKnkNNB6MtFHzV4PKxleup1+bi7eIN3IcgyvmvA2hSvkf1zp9p5MyV7lSwbhhfMNeeW5Ox22+Znx5gKVQioUfni+tPydM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668895; 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=za7wn1cNcTJGbyMmQnsrrq5f/3Xh3rNCM3vAYs6371A=; b=kDCPEM6ISfg1PVUkNDWxRQb54hbcTEsuL5HqM8hQ9nBpIBe0Yx6HdoGJuXDVzH1w58n0tQlSn+kYGQAjffHLr3f5+z9W43B3EickXsu3vAT1RwKYtWkjtcLwiOEhHAGtcXG1V0v5aGO1FwkppHQYgY1KcFt2+v716Q0m9mR4Vtg= 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 1646668895757998.7135075017856; Mon, 7 Mar 2022 08:01:35 -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-590-8gEANCYvMN29p8sEFiozFg-1; Mon, 07 Mar 2022 11:00:45 -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 1FF32866DFB; Mon, 7 Mar 2022 16:00:25 +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 19065401E37; Mon, 7 Mar 2022 16:00: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 B747D19305AF; Mon, 7 Mar 2022 16:00:23 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 1A00319305AE for ; Mon, 7 Mar 2022 16:00:14 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id DCB3A7D3CE; Mon, 7 Mar 2022 16:00:13 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3B3597DE5E for ; Mon, 7 Mar 2022 16:00:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668895; 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=za7wn1cNcTJGbyMmQnsrrq5f/3Xh3rNCM3vAYs6371A=; b=EY96iN1j4tBSGIMmDAziLa0QoJcZcIpnsTPubeXuwwPpz2UCCnoRVtP9zGA52hetWKiJ6H q+2xs+6KyYK0hm6aFtz8qsoZWLkbEocb6b1kXW6vHoHbViDagBQR+L/nkeL/S34tK9D1Lj Y6a26rMyX/AcJzkdKQ4F+ykfTNYriZQ= X-MC-Unique: 8gEANCYvMN29p8sEFiozFg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 15/17] docs: Convert 'formatsecret' page to rST Date: Mon, 7 Mar 2022 16:59:35 +0100 Message-Id: <7bc4f25997cc16f91c761b9ad930eaff905f8c3d.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668898118100001 Content-Type: text/plain; charset="utf-8" Also update the link from 'formatstorageencryption' to the 'usage-type-volume' anchor. Signed-off-by: Peter Krempa --- docs/formatsecret.html.in | 414 --------------------------- docs/formatsecret.rst | 337 ++++++++++++++++++++++ docs/formatstorageencryption.html.in | 2 +- docs/meson.build | 2 +- 4 files changed, 339 insertions(+), 416 deletions(-) delete mode 100644 docs/formatsecret.html.in create mode 100644 docs/formatsecret.rst diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in deleted file mode 100644 index 9dc9cdf288..0000000000 --- a/docs/formatsecret.html.in +++ /dev/null @@ -1,414 +0,0 @@ - - - - -

                Secret XML format

                - -
                  - -

                  Secret XML

                  - -

                  - Secrets stored by libvirt may have attributes associated with them, = using - the secret element. The secret element ha= s two - optional attributes, each with values 'yes' and - 'no', and defaulting to 'no': -

                  -
                  -
                  ephemeral
                  -
                  This secret must only be kept in memory, never stored persistent= ly. -
                  -
                  private
                  -
                  The value of the secret must not be revealed to any caller of li= bvirt, - nor to any other node. -
                  -
                  -

                  - The top-level secret element may contain the following - elements: -

                  -
                  -
                  uuid
                  -
                  - An unique identifier for this secret (not necessarily in the UUID - format). If omitted when defining a new secret, a random UUID is - generated. -
                  -
                  description
                  -
                  A human-readable description of the purpose of the secret. -
                  -
                  usage
                  -
                  - Specifies what this secret is used for. A mandatory - type attribute specifies the usage category, currently - only volume, ceph, iscsi, - tls, and vtpm are defined. Specific usage - categories are described below. -
                  -
                  - -

                  Usage type "volume"

                  - -

                  - This secret is associated with a volume, whether the format is either - for a "luks" encrypted volume. Each volume will have a - unique secret associated with it and it is safe to delete the - secret after the volume is deleted. The - <usage type=3D'volume'> element must contain a - single volume element that specifies the path of the vo= lume - this secret is associated with. For example, create a volume-secret.= xml - file as follows: -

                  - - 
                  -<secret ephemeral=3D'no' private=3D'yes'>
-   <description>Super secret name of my first puppy</description&=
gt;
-   <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid>
-   <usage type=3D'volume'>
-      <volume>/var/lib/libvirt/images/puppyname.img</volume>
-   </usage>
-</secret>
-
                  - -

                  - Define the secret and set the passphrase as follows: -

                  - 
                  -# virsh secret-define volume-secret.xml
-Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
-
                  - -

                  - See virsh secret-set-value on how - to set the value of the secret. -

                  - -

                  - The volume type secret can be supplied either in volume XML during - creation of a storage volu= me - in order to provide the passphrase to encrypt the volume or in - domain XML disk device - in order to provide the passphrase to decrypt the volume, - since 2.1.0. An example follows: -

                  - 
                  -# cat luks-secret.xml
-<secret ephemeral=3D'no' private=3D'yes'>
-   <description>LUKS Sample Secret</description>
-   <uuid>f52a81b2-424e-490c-823d-6bd4235bc57</uuid>
-   <usage type=3D'volume'>
-      <volume>/var/lib/libvirt/images/luks-sample.img</volume>
-   </usage>
-</secret>
-
-# virsh secret-define luks-secret.xml
-Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
-
                  -

                  - See virsh secret-set-value on how - to set the value of the secret. -

                  - -

                  - The volume type secret can be supplied in domain XML for a luks stor= age - volume encryption as fo= llows: -

                  - 
                  -<encryption format=3D'luks'>
-  <secret type=3D'passphrase' uuid=3D'f52a81b2-424e-490c-823d-6bd4235bc=
57'/>
-</encryption>
-
                  - -

                  Usage type "ceph"

                  -

                  - This secret is associated with a Ceph RBD (rados block device). - The <usage type=3D'ceph'> element must contain - a single name element that specifies a usage name - for the secret. The Ceph secret can then be used by UUID or by - this usage name via the <auth> element of - a disk device or - a storage pool (rbd). - Since 0.9.7. The following is an example - of the steps to be taken. First create a ceph-secret.xml file: -

                  - - 
                  -<secret ephemeral=3D'no' private=3D'yes'>
-   <description>CEPH passphrase example</description>
-   <usage type=3D'ceph'>
-      <name>ceph_example</name>
-   </usage>
-</secret>
-
                  - -

                  - Next, use virsh secret-define ceph-secret.xml to define - the secret and virsh secret-set-value using the generat= ed - UUID value and a base64 generated secret value in order to define the - chosen secret pass phrase. -

                  - 
                  -# virsh secret-define ceph-secret.xml
-Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created
-#
-# virsh secret-list
- UUID                                 Usage
------------------------------------------------------------
- 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
-
                  -

                  - See virsh secret-set-value on how - to set the value of the secret. -

                  - -

                  - The ceph secret can then be used by UUID or by the - usage name via the <auth> element in a domain's - <disk> - element as follows: -

                  - 
                  -<auth username=3D'myname'>
-  <secret type=3D'ceph' usage=3D'ceph_example'/>
-</auth>
-
                  - -

                  - As well as the <auth> element in a - storage pool (rbd) - <source> element as follows: -

                  - 
                  -<auth type=3D'ceph' username=3D'myname'>
-  <secret usage=3D'ceph_example'/>
-</auth>
-
                  - -

                  Usage type "iscsi"

                  - -

                  - This secret is associated with an iSCSI target for CHAP authenticati= on. - The <usage type=3D'iscsi'> element must contain - a single target element that specifies a usage name - for the secret. The iSCSI secret can then be used by UUID or by - this usage name via the <auth> element of - a disk device or - a storage pool (iscsi). - Since 1.0.4. The following is an example - of the XML that may be used to generate a secret for iSCSI CHAP - authentication. Assume the following sample entry in an iSCSI - authentication file: -

                  - 
                  -<target iqn.2013-07.com.example:iscsi-pool>
-backing-store /home/tgtd/iscsi-pool/disk1
-backing-store /home/tgtd/iscsi-pool/disk2
-incominguser myname mysecret
-</target>
-
                  -

                  - Define an iscsi-secret.xml file to describe the secret. Use the - incominguser username used in your iSCSI authentication - configuration file as the value for the username attrib= ute. - The description attribute should contain configuration - specific data. The target name may be any name of your - choosing to be used as the usage when used in the pool - or disk XML description. -

                  - 
                  -<secret ephemeral=3D'no' private=3D'yes'>
-   <description>Passphrase for the iSCSI example.com server</desc=
ription>
-   <usage type=3D'iscsi'>
-      <target>libvirtiscsi</target>
-   </usage>
-</secret>
-
                  - -

                  - Next, use virsh secret-define iscsi-secret.xml to define - the secret and - virsh secret-set-value - using the generated - UUID value and a base64 generated secret value in order to define the - chosen secret pass phrase. The pass phrase must match the password - used in the iSCSI authentication configuration file. -

                  - 
                  -# virsh secret-define secret.xml
-Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
-
-# virsh secret-list
- UUID                                 Usage
------------------------------------------------------------
- c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi
-
-
                  - -

                  - See virsh secret-set-value on how - to set the value of the secret. -

                  - -

                  - The iSCSI secret can then be used by UUID or by the - usage name via the <auth> element in a domain's - <disk> - element as follows: -

                  - 
                  -<auth username=3D'myname'>
-  <secret type=3D'iscsi' usage=3D'libvirtiscsi'/>
-</auth>
-
                  - -

                  - As well as the <auth> element in a - storage pool (iscsi) - <source> element as follows: -

                  - 
                  -<auth type=3D'chap' username=3D'myname'>
-  <secret usage=3D'libvirtiscsi'/>
-</auth>
-
                  - -

                  Usage type "tls"

                  - -

                  - This secret may be used in order to provide the passphrase for the - private key used to provide TLS credentials. - The <usage type=3D'tls'> element must contain a - single name element that specifies a usage name - for the secret. - Since 2.3.0. - The following is an example of the expected XML and processing to - define the secret: -

                  - - 
                  -# cat tls-secret.xml
-<secret ephemeral=3D'no' private=3D'yes'>
-   <description>sample tls secret</description>
-   <usage type=3D'tls'>
-      <name>TLS_example</name>
-   </usage>
-</secret>
-
-# virsh secret-define tls-secret.xml
-Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
-
-# virsh secret-list
- UUID                                 Usage
------------------------------------------------------------
- 718c71bd-67b5-4a2b-87ec-a24e8ca200dc  tls TLS_example
-#
-
-
                  - -

                  - A secret may also be defined via the - - virSecretDefineXML API. - - Once the secret is defined, a secret value will need to be set. The - secret would be the passphrase used to access the TLS credentials. - The following is a simple example of using - virsh secret-set-value = to set - the secret value. The - - virSecretSetValue API may also be used to set - a more secure secret without using printable/readable characters. -

                  - -

                  Usage type "vtpm"

                  - -

                  - This secret is associated with a virtualized TPM (vTPM) and serves - as a passphrase for deriving a key from for encrypting the state - of the vTPM. - The <usage type=3D'vtpm'> element must contain - a single name element that specifies a usage name - for the secret. The vTPM secret can then be used by UUID - via the <encryption> element of - a tpm when using an - emulator. - Since 5.6.0. The following is an example - of the steps to be taken. First create a vtpm-secret.xml file: <= /p> - - 

                  -# cat vtpm-secret.xml
-<secret ephemeral=3D'no' private=3D'yes'>
-   <description>sample vTPM secret</description>
-   <usage type=3D'vtpm'>
-      <name>VTPM_example</name>
-   </usage>
-</secret>
-
-# virsh secret-define vtpm-secret.xml
-Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created
-
-# virsh secret-list
- UUID                                   Usage
---------------------------------------------------------------------------=
--------------
- 6dd3e4a5-1d76-44ce-961f-f119f5aad935   vtpm VTPM_example
-
-#
-
-
                  - -

                  - A secret may also be defined via the - - virSecretDefineXML API. - - Once the secret is defined, a secret value will need to be set. The - secret would be the passphrase used to decrypt the vTPM state. - The following is a simple example of using - virsh secret-set-value - to set the secret value. The - - virSecretSetValue API may also be used to set - a more secure secret without using printable/readable characters. -

                  - -

                  Setting secret values in virsh

                  - -

                  - To set the value of the secret you can use the following virsh comma= nds. - If the secret is a password-like string (printable characters, no ne= wline) - you can use: -

                  - 
                  -# virsh secret-set-value --interactive 6dd3e4a5-1d76-44ce-961f-f119f5aad935
-Enter new value for secret:
-Secret value set
-
                  - -

                  - Another secure option is to read the secret from a file. This way the - secret can contain any bytes (even NUL and non-printable characters)= . The - length of the secret is the length of the input file. Alternatively = the - --plain option can be omitted if the file contents are - base64-encoded. -

                  - - 
                  -# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file --pla=
in secretinfile
-Secret value set
-
                  - -

                  - WARNING The following approach is insecure and depreca= ted. - The secret can also be set via an argument. Note that other users ma= y see - the actual secret in the process listing! - The secret must be base64 encoded. -

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

                  Examples

                  - Assuming a + Assuming a luks volume type secret is already defined, a simple example specifying use of the luks format for either volume creation without a specific cipher being defined or diff --git a/docs/meson.build b/docs/meson.build index fce6533301..f614bcadeb 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -46,7 +46,6 @@ docs_html_in_files =3D [ 'formatnetworkport', 'formatnode', 'formatnwfilter', - 'formatsecret', 'formatstoragecaps', 'formatstorageencryption', 'hooks', @@ -93,6 +92,7 @@ docs_rst_files =3D [ 'formatbackup', 'formatcheckpoint', 'formatdomain', + 'formatsecret', 'formatsnapshot', 'formatstorage', 'glib-adoption', --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668922; cv=none; d=zohomail.com; s=zohoarc; b=G5G36LvDWsl8uWN9b37LIe+Z28V+X3NHxPxbypBqDim6V0zwdHnyuXzCfySPookmymVDlldtZja2VCrqHS1IWe3NNgz4H7bjmfM8ImQDQZx84k9a2kbxChc5mvDmibbZKstAZgXUrTf+0jeqPUGyNX5Nj0pPkmEIppv37C66/II= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668922; 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=2gRVgphxy9IjQ4dbGDS8MnwFraokiBNtGaVyzKX+L/I=; b=cCrzHZFWcmOPwnkCzh4WlUDViwqSFHOcJqAkVOX7Gyp7OKXBWFeqrC3wSMYwfmtUp+kFaBvNI7OD8lSgJgEn8eXBr8DV/Dabi8Qrel4HwIXLAHxu826ARwqhGwmCNBuPhL58u1LHJXVh/wBY8lPY5KZWWlz85D+PBUKDKVyj5Io= 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 1646668922320579.9167116763266; Mon, 7 Mar 2022 08:02:02 -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-256-DXDt7CIaPsaN7diWGa2uUw-1; Mon, 07 Mar 2022 11:00:37 -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 D0D313817499; Mon, 7 Mar 2022 16:00:17 +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 B81DF40CFD06; Mon, 7 Mar 2022 16:00:17 +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 7409A196BB94; Mon, 7 Mar 2022 16:00:17 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 2222419305AE for ; Mon, 7 Mar 2022 16:00:15 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id E9F1D7DE5E; Mon, 7 Mar 2022 16:00:14 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 57A627D3CE for ; Mon, 7 Mar 2022 16:00:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668922; 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=2gRVgphxy9IjQ4dbGDS8MnwFraokiBNtGaVyzKX+L/I=; b=MbvLbod3KI6LyS/uaM+biAa6r/J0aogv+TzCMtFVxxuVr9AtLfspg40MGSci+3ujww0jV1 +/QuslJx2m0yG4AvztZawJ3/K1ArdZwiviRpmxhpDQPj9kZ2NYAafmHOZLc4ImL/6496iC nJh1LC7XUq/6tje9XCFZibBpDEm8FpE= X-MC-Unique: DXDt7CIaPsaN7diWGa2uUw-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 16/17] docs: formatsecret: Drop few unneeded empty lines Date: Mon, 7 Mar 2022 16:59:36 +0100 Message-Id: <4857a0034e68d069ca989a6c74485b84866e2bce.1646668723.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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: 1646668924287100001 Content-Type: text/plain; charset="utf-8" The examples contain some whitespace and command prompts which just waste space. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/formatsecret.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/formatsecret.rst b/docs/formatsecret.rst index a3ffb7c4b9..15b2a221d7 100644 --- a/docs/formatsecret.rst +++ b/docs/formatsecret.rst @@ -251,8 +251,6 @@ processing to define the secret: UUID Usage ----------------------------------------------------------- 718c71bd-67b5-4a2b-87ec-a24e8ca200dc tls TLS_example - # - A secret may also be defined via the `virSecretDefineXML `= __ @@ -292,9 +290,6 @@ the steps to be taken. First create a vtpm-secret.xml f= ile: -----------------------------------------------------------------------= ----------------- 6dd3e4a5-1d76-44ce-961f-f119f5aad935 vtpm VTPM_example - # - - A secret may also be defined via the `virSecretDefineXML `= __ API. Once the secret is defined, a secret value will need to be set. The s= ecret --=20 2.35.1 From nobody Fri May 10 12:06:15 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=1646668919; cv=none; d=zohomail.com; s=zohoarc; b=fz2EMgLIbD5EmB+McuvuC0juHiQl7BcjEzruRc+4JAu0ADzUvYvbxzG57O7F3508lDK7G2mM2Hw1Inq2W60CdefJ46Cy8g+t4W07mhxsBHIcUA0bRTvR5F5gFcPFSdj5yLQTBO01FfhY10bpB5QXG0ILxUHNBzqf1uX9L8Oa1mA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1646668919; 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=j87Fr6msXKw9DXXSVTTfxWwc4GGRjByxF50gkqXEZoQ=; b=BuLUszhi/j569GzeTCPXm/rcc5n5UR9jznxXUB7FQvidmyq7td37Ptw+mFC+2eEvyHVGFs/+fL/P5CkK2OfrgC5/t5P0FOkvpYx+E9mA2dn9iQl/y+0K3P40To1JWDrU/SLLwQv9NH4jzLtiR2BZ6TdrDEsVOXkJ0SSM6anJgqY= 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 1646668919317824.3698285121001; Mon, 7 Mar 2022 08:01:59 -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-32-txph3yLLN3qoWsZhsAuG0w-1; Mon, 07 Mar 2022 11:00:41 -0500 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id AAC41381748B; Mon, 7 Mar 2022 16:00:17 +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 9354F40D1B9E; Mon, 7 Mar 2022 16:00:17 +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 61EFC19305AF; Mon, 7 Mar 2022 16:00:17 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 5FAEB19305AE for ; Mon, 7 Mar 2022 16:00:16 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 234B882769; Mon, 7 Mar 2022 16:00:16 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.30]) by smtp.corp.redhat.com (Postfix) with ESMTP id 677377D3CE for ; Mon, 7 Mar 2022 16:00:15 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1646668918; 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=j87Fr6msXKw9DXXSVTTfxWwc4GGRjByxF50gkqXEZoQ=; b=e7Ab1l2AU27hNj8PaQW6lTFIKm1Ntc7hN61FDBQ1w3IDeyn+MVsjFwRlxH3f9SWitB/tR8 WSssGdKBRWVtQLkHNhUtn2U58iZCnVHe0U/m7l5w/2fPQ25gEm480bd6VNcg6JhsqDsL6b XtalFcDnPV+ElAQuSbuoaWPNYligtoU= X-MC-Unique: txph3yLLN3qoWsZhsAuG0w-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 17/17] docs: meson: Restore alphabetical order Date: Mon, 7 Mar 2022 16:59:37 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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.2 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: 1646668921463100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/meson.build | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/meson.build b/docs/meson.build index f614bcadeb..7146bd078b 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -39,9 +39,9 @@ docs_html_in_files =3D [ 'drvvmware', 'drvxen', 'firewall', + 'format', 'formatcaps', 'formatdomaincaps', - 'format', 'formatnetwork', 'formatnetworkport', 'formatnode', @@ -70,13 +70,13 @@ docs_html_in_files =3D [ docs_rst_files =3D [ 'aclpolkit', 'advanced-tests', - 'api_extension', 'api', + 'api_extension', 'apps', 'auditlog', 'auth', - 'bindings', 'best-practices', + 'bindings', 'bugs', 'ci', 'coding-style', @@ -86,8 +86,8 @@ docs_rst_files =3D [ 'daemons', 'developer-tooling', 'drivers', - 'drvqemu', 'drvch', + 'drvqemu', 'errors', 'formatbackup', 'formatcheckpoint', --=20 2.35.1