From nobody Fri May 10 15:26:10 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=1649084682; cv=none; d=zohomail.com; s=zohoarc; b=mH/J+ggCCpNnToSgc6g6Yv1rSGT6Abc8LKxU3oyAlXEg64jvk2jnalHE8tjzWF99z9fCuITzUKoe2s1reszNRwl2+CDEtocuxbsXKHE1fgsEf7ii69mO3lXBgeg9RqAElTARUVYO1nR355SxLx/Tn014Zy21gZ011D43y0zkS5c= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649084682; 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=6wMjBMN6q6QqGqcslj4GFAwZUun06Bt56aM/QeWCIBM=; b=AAi4vrPwOS2DMhNmXZsbScwmDfWZbNfqyL7DyP65HWeX5ml3R5UBQYpW3GYfM+9a7CrrDA/I1hYuZJDykHWdoLHtAS8ZNCPEvk9Qy0cfL/IyuZLh2aDr1xxvrpJmyVK4TRdsP0XUnYwV5735KTqKE66Ei4CeSTbaIoj1QV58Jgw= 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 1649084682089452.54030977222396; Mon, 4 Apr 2022 08:04:42 -0700 (PDT) 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-371-jucsg8OxNKu-JY3vZhaufg-1; Mon, 04 Apr 2022 11:04:37 -0400 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 72E2D2805522; Mon, 4 Apr 2022 15:04:30 +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 1F449C28111; Mon, 4 Apr 2022 15:04:30 +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 5440D19451F2; Mon, 4 Apr 2022 15:04:29 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 7926519451EF for ; Mon, 4 Apr 2022 15:04:27 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 6736114582FB; Mon, 4 Apr 2022 15:04:27 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id C013C14583CB for ; Mon, 4 Apr 2022 15:04:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649084680; 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=6wMjBMN6q6QqGqcslj4GFAwZUun06Bt56aM/QeWCIBM=; b=g6gfbqNcZ+FzWd72K8XR+kynYJJHdIbMpCxjNr0RbSP0nWAOUsQN6WTARM/Tg3EEeglPOD VYzRmlFDhMsi5ub0I4UF2taAK1rR8DMbR7yE2gtuVE7/dU8Rzh8XxiGhVuc9X4lp754QUj Lu2FRiFkkga9RZ/Pc2jP7utcd68kzZo= X-MC-Unique: jucsg8OxNKu-JY3vZhaufg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 1/7] docs: convert 'dbus' page to rst Date: Mon, 4 Apr 2022 17:04:18 +0200 Message-Id: <5bee2d540e953949ad9f99cac8c6c718890ad3b9.1649084492.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 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: 8bit Content-Type: application/octet-stream; x-default=true X-Zoho-Virus-Status: 1 X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649084683963100001 From: Pavel Hrdina Signed-off-by: Pavel Hrdina Signed-off-by: Peter Krempa --- docs/dbus.html.in | 94 ----------------------------------------------- docs/dbus.rst | 75 +++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 76 insertions(+), 95 deletions(-) delete mode 100644 docs/dbus.html.in create mode 100644 docs/dbus.rst diff --git a/docs/dbus.html.in b/docs/dbus.html.in deleted file mode 100644 index 99f191a685..0000000000 --- a/docs/dbus.html.in +++ /dev/null @@ -1,94 +0,0 @@ - - - - -

D-Bus API bindings

- -
    - -

    Description

    - -

    - libvirt-dbus wraps libvirt API to provide a high-level object-oriented - API better suited for dbus-based applications. -

    - -

    GIT source repository

    -

    - The D-Bus bindings source code is maintained in a - git repository available on - gitlab.com: -

    - -
    -git clone https://gitlab.com/libvirt/libvirt-dbus.git
-
    - -

    Usage

    - -

    - libvirt-dbus exports libvirt API using D-Bus objects with methods and - properties described by interfaces. Currently only local connection - to libvirt is exported and the list of supported drivers depends - on the type of the bus connection (session or system). -

    - -

    - The name of the libvirt-dbus service is org.libvirt. - libvirt-dbus distributes an interface XML descriptions which can be - usually found at /usr/share/dbus-1/interfaces/. -

    - -

    - By default unprivileged user has access only to the session D-Bus - connection. In order to allow specific user "foo" to access the system - D-Bus connection you need to create a file - /etc/dbus-1/system.d/org.libvirt.conf that contains: -

    - -
    -<?xml version="1.0"?>
-<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
- "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
-
-<busconfig>
-
-  <policy user="foo">
-    <allow send_destination="org.libvirt"/>
-  </policy>
-
-</busconfig>
-
    - -

    - To get a list of supported drivers for the specific bus connection - you can run these commands (not all drivers may be available on - the host): -

    - -
    -gdbus introspect --xml --session --dest org.libvirt --object-path /org/libvirt
-gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt
-
    - -

    - Every object is introspectable so you can get a list of available - interfaces with methods, signals and properties running this command: -

    - -
    -gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt/QEMU
-
    - -

    - To get a list of domains for specific connection driver you can run - this command: -

    - -
    -gdbus call --system --dest org.libvirt --object-path /org/libvirt/QEMU \
-    --method org.libvirt.Connect.ListDomains 0
-
    - - - diff --git a/docs/dbus.rst b/docs/dbus.rst new file mode 100644 index 0000000000..f026dc0aba --- /dev/null +++ b/docs/dbus.rst @@ -0,0 +1,75 @@ +================== +D-Bus API bindings +================== + +.. contents:: + +Description +----------- + +libvirt-dbus wraps libvirt API to provide a high-level object-oriented API +better suited for dbus-based applications. + +GIT source repository +--------------------- + +The D-Bus bindings source code is maintained in a `git `__ +repository available on +`gitlab.com `__: + +:: + + git clone https://gitlab.com/libvirt/libvirt-dbus.git + +Usage +----- + +libvirt-dbus exports libvirt API using D-Bus objects with methods and properties +described by interfaces. Currently only local connection to libvirt is exported +and the list of supported drivers depends on the type of the bus connection +(session or system). + +The name of the libvirt-dbus service is ``org.libvirt``. libvirt-dbus +distributes an interface XML descriptions which can be usually found at +``/usr/share/dbus-1/interfaces/``. + +By default unprivileged user has access only to the session D-Bus connection. In +order to allow specific user "foo" to access the system D-Bus connection you +need to create a file ``/etc/dbus-1/system.d/org.libvirt.conf`` that contains: + +:: + + + + + + + + + + + + +To get a list of supported drivers for the specific bus connection you can run +these commands (not all drivers may be available on the host): + +:: + + gdbus introspect --xml --session --dest org.libvirt --object-path /org/libvirt + gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt + +Every object is introspectable so you can get a list of available interfaces +with methods, signals and properties running this command: + +:: + + gdbus introspect --xml --system --dest org.libvirt --object-path /org/libvirt/QEMU + +To get a list of domains for specific connection driver you can run this +command: + +:: + + gdbus call --system --dest org.libvirt --object-path /org/libvirt/QEMU \ + --method org.libvirt.Connect.ListDomains 0 diff --git a/docs/meson.build b/docs/meson.build index 6effe4f838..e73cb3c6cd 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -20,7 +20,6 @@ docs_assets = [ docs_html_in_files = [ '404', 'csharp', - 'dbus', 'docs', 'formatcaps', 'formatdomaincaps', @@ -57,6 +56,7 @@ docs_rst_files = [ 'contact', 'contribute', 'daemons', + 'dbus', 'downloads', 'drivers', 'drvbhyve', -- 2.35.1 From nobody Fri May 10 15:26:10 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=1649084769; cv=none; d=zohomail.com; s=zohoarc; b=ZdXY1ObHgWPvoPCERHSeUYgiur1pjbTrPK8bxIOzKdlD2pPyyglIKDyFWJJwssPZHTOuIwGFNeJPzUP+X0gG2EmE/3ZWDMqSjkSYIcrHjJujipjK9yj9rYrYmC4GawOWwVf72XpJLJEQxsl7SNCM7E8ZwiGU8nIhNncvLZW0WPM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649084769; 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=I60ER2CWCPRklHmNKtIROyhoEzh3ENbHlTZnueEvFmI=; b=lDm99nnfA6A3zafEEQVeI53mth+ov5907CXByNwOqeE8xJmjHOHttiJnPPiWgfkhMib5QKaA5yoUqL/dKDnBxyhPNfer0hIfygC0dd0NU0CtIzGJ/lS2BmTkrVyadmXQKCjbdQef7ljj5YvmTpK9JPVwAcTJ6wFlIWp99JSeJl4= 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 164908476919578.50600988799351; Mon, 4 Apr 2022 08:06:09 -0700 (PDT) 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-107-e-yybDXbOhqe4qW4QgIEbg-1; Mon, 04 Apr 2022 11:04:40 -0400 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 A3F0E811E76; Mon, 4 Apr 2022 15:04:30 +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 8E549C28107; Mon, 4 Apr 2022 15:04:30 +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 A29CD194037C; Mon, 4 Apr 2022 15:04:29 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 5D1E01940367 for ; Mon, 4 Apr 2022 15:04:28 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 422E314583CB; Mon, 4 Apr 2022 15:04:28 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id BD42914582FB for ; Mon, 4 Apr 2022 15:04:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649084768; 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=I60ER2CWCPRklHmNKtIROyhoEzh3ENbHlTZnueEvFmI=; b=THFwvCe3Qzz8gzi1ljLPscySqGehmBlR0NHMZ+ZeNmYSKvyERzNairmA9duVBkFKs+eeBH H/q0yh389+iGpelegBySK7nheEbqd+GVpzeJCOXoukjuMkSV1AlthqQSisxuNLTge4iu8a ZDXDSSZ1R8vc9muG/9dCA2nxmNAEN90= X-MC-Unique: e-yybDXbOhqe4qW4QgIEbg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 2/7] docs: convert 'python' page to rst Date: Mon, 4 Apr 2022 17:04:19 +0200 Message-Id: <3b0132a8c82d040d9cbc31357c73913caf8fcd9d.1649084492.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 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: 8bit Content-Type: application/octet-stream; x-default=true X-Zoho-Virus-Status: 1 X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649084770780100001 From: Pavel Hrdina Signed-off-by: Pavel Hrdina Signed-off-by: Peter Krempa --- docs/meson.build | 2 +- docs/python.html.in | 72 ----------------------------------------- docs/python.rst | 79 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 73 deletions(-) delete mode 100644 docs/python.html.in create mode 100644 docs/python.rst diff --git a/docs/meson.build b/docs/meson.build index e73cb3c6cd..9022e761ca 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -29,7 +29,6 @@ docs_html_in_files = [ 'formatstoragecaps', 'index', 'internals', - 'python', 'remote', 'storage', 'tlscerts', @@ -102,6 +101,7 @@ docs_rst_files = [ 'php', 'platforms', 'programming-languages', + 'python', 'securityprocess', 'strategy', 'styleguide', diff --git a/docs/python.html.in b/docs/python.html.in deleted file mode 100644 index 0f804da8c3..0000000000 --- a/docs/python.html.in +++ /dev/null @@ -1,72 +0,0 @@ - - - - -

    Python API bindings

    - -

    The Python binding should be complete and are mostly automatically -generated from the formal description of the API in xml. The bindings are -articulated around 2 classes virConnect and virDomain mapping to -the C types. Functions in the C API taking either type as argument then -becomes methods for the classes, their name is just stripped from the -virConnect or virDomain(Get) prefix and the first letter gets converted to -lower case, for example the C functions:

    -

    - int virConnectNumOfDomains -(virConnectPtr conn); -

    -

    - int virDomainSetMaxMemory -(virDomainPtr domain, unsigned long memory); -

    -

    become

    -

    - virConnect::numOfDomains(self) -

    -

    - virDomain::setMaxMemory(self, memory) -

    -

    This process is fully automated, you can get a summary of the conversion -in the file libvirtclass.txt present in the python dir or in the docs.There -is a couple of function who don't map directly to their C counterparts due to -specificities in their argument conversions:

    -
      -
    • virConnectListDomains - is replaced by virDomain::listDomainsID(self) which returns - a list of the integer ID for the currently running domains
      • -
    • virDomainGetInfo - is replaced by virDomain::info() which returns a list of -
      1. state: one of the state values (virDomainState)
      2. maxMemory: the maximum memory used by the domain
      3. memory: the current amount of memory used by the domain
      4. nbVirtCPU: the number of virtual CPU
      5. cpuTime: the time used by the domain in nanoseconds
      • -
    -

    So let's look at a simple example:

    - 
    import libvirt
-import sys
-
-try:
-    conn = libvirt.openReadOnly(None)
-except libvirt.libvirtError:
-    print('Failed to open connection to the hypervisor')
-    sys.exit(1)
-
-try:
-    dom0 = conn.lookupByName("Domain-0")
-except libvirt.libvirtError:
-    print('Failed to find the main domain')
-    sys.exit(1)
-
-print("Domain 0: id %d running %s" % (dom0.ID(), dom0.OSType()))
-print(dom0.info())
    -

    There is not much to comment about it, it really is a straight mapping -from the C API, the only points to notice are:

    -
      -
    • the import of the module called libvirt
      • -
    • getting a connection to the hypervisor, in that case using the - openReadOnly function allows the code to execute as a normal user.
      • -
    • getting an object representing the Domain 0 using lookupByName
      • -
    • if the domain is not found a libvirtError exception will be raised
      • -
    • extracting and printing some information about the domain using - various methods - associated to the virDomain class.
      • -
    - - diff --git a/docs/python.rst b/docs/python.rst new file mode 100644 index 0000000000..aa1bddc4e1 --- /dev/null +++ b/docs/python.rst @@ -0,0 +1,79 @@ +=================== +Python API bindings +=================== + +The Python binding should be complete and are mostly automatically generated +from the formal description of the API in xml. The bindings are articulated +around 2 classes ``virConnect`` and virDomain mapping to the C types. Functions +in the C API taking either type as argument then becomes methods for the +classes, their name is just stripped from the virConnect or virDomain(Get) +prefix and the first letter gets converted to lower case, for example the C +functions: + +``int virConnectNumOfDomains (virConnectPtr conn);`` + +``int virDomainSetMaxMemory (virDomainPtr domain, unsigned long memory);`` + +become + +``virConnect::numOfDomains(self)`` + +``virDomain::setMaxMemory(self, memory)`` + +This process is fully automated, you can get a summary of the conversion in the +file libvirtclass.txt present in the python dir or in the docs.There is a couple +of function who don't map directly to their C counterparts due to specificities +in their argument conversions: + +- ``virConnectListDomains`` is replaced by ``virDomain::listDomainsID(self)`` + which returns a list of the integer ID for the currently running domains + +- ``virDomainGetInfo`` is replaced by ``virDomain::info()`` which returns a + list of + + #. state: one of the state values (virDomainState) + + #. maxMemory: the maximum memory used by the domain + + #. memory: the current amount of memory used by the domain + + #. nbVirtCPU: the number of virtual CPU + + #. cpuTime: the time used by the domain in nanoseconds + +So let's look at a simple example: + +:: + + import libvirt + import sys + + try: + conn = libvirt.openReadOnly(None) + except libvirt.libvirtError: + print('Failed to open connection to the hypervisor') + sys.exit(1) + + try: + dom0 = conn.lookupByName("Domain-0") + except libvirt.libvirtError: + print('Failed to find the main domain') + sys.exit(1) + + print("Domain 0: id %d running %s" % (dom0.ID(), dom0.OSType())) + print(dom0.info()) + +There is not much to comment about it, it really is a straight mapping from the +C API, the only points to notice are: + +- the import of the module called ``libvirt`` + +- getting a connection to the hypervisor, in that case using the openReadOnly + function allows the code to execute as a normal user. + +- getting an object representing the Domain 0 using lookupByName + +- if the domain is not found a libvirtError exception will be raised + +- extracting and printing some information about the domain using various + methods associated to the virDomain class. -- 2.35.1 From nobody Fri May 10 15:26:10 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=1649084688; cv=none; d=zohomail.com; s=zohoarc; b=RiS97FEhaCVPtfkPg5wQOU0towSpSxR6qClhRvsb+niZ/HK9GDr1ghLEG0DeMDstJNVBrdPZk2NcF/p+LFFbPdArcDLoxEY61/Y9e0IU46M0HpYydI4/2kbifdAJhC3LyxtnA0TzfoRl27p5FQalkII52cD/q40aQT2d1iOlzdA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649084688; 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=Tczj5dKiAyLhqljaa1HwGTRLraj6GV8CbvlsQiqUYaw=; b=cT2MDZ5IYklE+h3ivPcri8nV2cV2zkoVY3yp0rYDFLxCJFBISrHg1u/Jpa3ACLhS/BK7wVZn9REeqa2FUouU0TKHmTEc2Auhd3K+FH9umUcNvpjqwa17thlPmh1fQ/ARuXZ2+4tqdxj9CANgwPaOmmak9JiXKTE9oKzpMoctOlE= 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 1649084688077618.7535456674865; Mon, 4 Apr 2022 08:04:48 -0700 (PDT) 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-38-G85wdLlwPySncoIrQ2xfOw-1; Mon, 04 Apr 2022 11:04:41 -0400 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 43020100BAA7; Mon, 4 Apr 2022 15:04:31 +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 2D07940D0174; Mon, 4 Apr 2022 15:04:31 +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 F1ABB193F6E3; Mon, 4 Apr 2022 15:04:29 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 6E0C71940373 for ; Mon, 4 Apr 2022 15:04:29 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 6237414583F1; Mon, 4 Apr 2022 15:04:29 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id AC0A514583D1 for ; Mon, 4 Apr 2022 15:04:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649084687; 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=Tczj5dKiAyLhqljaa1HwGTRLraj6GV8CbvlsQiqUYaw=; b=H9UgN/s1MKgu66tPoRweNNJy2SZwRlVG2rv25kRBYzf2Ppx5Kn4pRqdx4XN0p1flYCvf4E YyGgGHAh6bDUg91BYvy+XA+OShVHOSow0vQTj/+ouBpzXvoYfIsUDlqP0JaNBku1KbIz8Z WIqhcyrrHlPlgPovO8lA/9Iz9ltCwpA= X-MC-Unique: G85wdLlwPySncoIrQ2xfOw-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 3/7] docs: convert 'tlscerts' page to rst Date: Mon, 4 Apr 2022 17:04:20 +0200 Message-Id: <116ad9fded7ce0e3b5b77fa51e562d1ff3074507.1649084492.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 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: 8bit Content-Type: application/octet-stream; x-default=true X-Zoho-Virus-Status: 1 X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649084690036100003 From: Pavel Hrdina Note that links from the first table leading to sections of this document further below were removed for simplicity. Signed-off-by: Pavel Hrdina Signed-off-by: Peter Krempa --- docs/meson.build | 2 +- docs/tlscerts.html.in | 413 ------------------------------------------ docs/tlscerts.rst | 331 +++++++++++++++++++++++++++++++++ 3 files changed, 332 insertions(+), 414 deletions(-) delete mode 100644 docs/tlscerts.html.in create mode 100644 docs/tlscerts.rst diff --git a/docs/meson.build b/docs/meson.build index 9022e761ca..8b174fe41e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -31,7 +31,6 @@ docs_html_in_files = [ 'internals', 'remote', 'storage', - 'tlscerts', 'uri', 'windows', ] @@ -110,6 +109,7 @@ docs_rst_files = [ 'testapi', 'testsuites', 'testtck', + 'tlscerts', ] # list of web targets to build for docs/web rule diff --git a/docs/tlscerts.html.in b/docs/tlscerts.html.in deleted file mode 100644 index 5b7a5f56e4..0000000000 --- a/docs/tlscerts.html.in +++ /dev/null @@ -1,413 +0,0 @@ - - - - -

    TLS x509 certificate setup

    - -
      - -

      - Public Key Infrastructure set up -

      -

      -If you are unsure how to create TLS certificates, skip to the -next section. -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      Location Machine Description Required fields
      - /etc/pki/CA/cacert.pem - Installed on the client and server CA's certificate (more info) n/a
      - $HOME/.pki/cacert.pem - Installed on the client CA's certificate (more info) n/a
      - /etc/pki/libvirt/private/serverkey.pem - Installed on the server Server's private key (more info) n/a
      - /etc/pki/libvirt/servercert.pem - Installed on the server Server's certificate signed by the CA. - (more info) CommonName (CN) must be the hostname of the server as it - is seen by clients. All hostname and IP address variants that might - be used to reach the server should be listed in Subject Alt Name - fields.
      - /etc/pki/libvirt/private/clientkey.pem - Installed on the client Client's private key. (more info) n/a
      - /etc/pki/libvirt/clientcert.pem - Installed on the client Client's certificate signed by the CA - (more info) Distinguished Name (DN) can be checked against an access - control list (tls_allowed_dn_list). -
      - $HOME/.pki/libvirt/clientkey.pem - Installed on the client Client's private key. (more info) n/a
      - $HOME/.pki/libvirt/clientcert.pem - Installed on the client Client's certificate signed by the CA - (more info) Distinguished Name (DN) can be checked against an access - control list (tls_allowed_dn_list). -
      -

      - If 'pkipath' is specified in URI, then all the client - certificates must be found in the path specified, otherwise the - connection will fail with a fatal error. If 'pkipath' is not - specified: -

      -
        -
      • For a non-root user, libvirt tries to find the certificates - in $HOME/.pki/libvirt first. If the required CA certificate cannot - be found, then the global default location - (/etc/pki/CA/cacert.pem) will be used. - Likewise, if either the client certificate - or the client key cannot be found, then the global default - locations (/etc/pki/libvirt/clientcert.pem, - /etc/pki/libvirt/private/clientkey.pem) will be used. -
        • -
      • For the root user, the global default locations will always be used.
        • -
      -

      - Background to TLS certificates -

      -

      -Libvirt supports TLS certificates for verifying the identity -of the server and clients. There are two distinct checks involved: -

      -
        -
      • The client should know that it is connecting to the right -server. Checking done by client by matching the certificate that -the server sends to the server's hostname. May be disabled by adding -?no_verify=1 to the -remote URI. -
        • -
      • The server should know that only permitted clients are -connecting. This can be done based on client's IP address, or on -client's IP address and client's certificate. Checking done by the - server. May be enabled and disabled in the libvirtd.conf file. -
        • -
      -

      -For full certificate checking you will need to have certificates -issued by a recognised Certificate -Authority (CA) for your server(s) and all clients. To avoid the -expense of getting certificates from a commercial CA, you can set up -your own CA and tell your server(s) and clients to trust certificates -issues by your own CA. Follow the instructions in the next section. -

      -

      -Be aware that the default -configuration for libvirtd allows any client to connect provided -they have a valid certificate issued by the CA for their own IP -address. You may want to change this to make it less (or more) -permissive, depending on your needs. -

      -

      - Setting up a Certificate Authority (CA) -

      -

      -You will need the GnuTLS -certtool program documented here. In Fedora, it is in the -gnutls-utils package. -

      -

      -Create a private key for your CA: -

      - 
      -certtool --generate-privkey > cakey.pem
-
      -

      -and self-sign it by creating a file with the -signature details called -ca.info containing: -

      - 
      -cn = Name of your organization
-ca
-cert_signing_key
-
      - 
      -certtool --generate-self-signed --load-privkey cakey.pem \
-  --template ca.info --outfile cacert.pem
-
      -

      -(You can delete ca.info file now if you -want). -

      -

      -Now you have two files which matter: -

      -
        -
      • cakey.pem - Your CA's private key (keep this very secret!) -
        • -
      • cacert.pem - Your CA's certificate (this is public). -
        • -
      -

      cacert.pem has to be installed on clients and -server(s) to let them know that they can trust certificates issued by -your CA. -

      -

      -The normal installation directory for cacert.pem -is /etc/pki/CA/cacert.pem on all clients and servers. -

      -

      -To see the contents of this file, do: -

      - 
      certtool -i --infile cacert.pem
-
-X.509 certificate info:
-
-Version: 3
-Serial Number (hex): 00
-Subject: CN=Libvirt Project
-Issuer: CN=Libvirt Project
-Signature Algorithm: RSA-SHA
-Validity:
-        Not Before: Mon Jun 18 16:22:18 2007
-        Not After: Tue Jun 17 16:22:18 2008
-[etc]
-
      -

      -This is all that is required to set up your CA. Keep the CA's private -key carefully as you will need it when you come to issue certificates -for your clients and servers. -

      -

      - Issuing server certificates -

      -

      -For each server (libvirtd) you need to issue a certificate -containing one or more hostnames and/or IP addresses. -Historically the CommonName (CN) field would contain the -hostname of the server and would match the hostname used -in the URI that clients pass to libvirt. In most TLS implementations -the CN field is considered legacy data. The preferential mechanism -is to use Subject Alt Name (SAN) extension fields to validate -against. In the future use of the CN field for validation may be -discontinued entirely, so it is strongly recommended to -include the SAN fields. -

      -

      -In the example below, clients will be connecting to the -server using a URI of -qemu://compute1.libvirt.org/system, so the CN -must be "compute1.libvirt.org". -

      -

      -Make a private key for the server: -

      - 
      -certtool --generate-privkey > serverkey.pem
-
      -

      -and sign that key with the CA's private key by first -creating a template file called server.info. -The template file will contain a number of fields to define -the server as follows: -

      - 
      -organization = Name of your organization
-cn = compute1.libvirt.org
-dns_name = compute1
-dns_name = compute1.libvirt.org
-ip_address = 10.0.0.74
-ip_address = 192.168.1.24
-ip_address = 2001:cafe::74
-ip_address = fe20::24
-tls_www_server
-encryption_key
-signing_key
-
      -

      -The 'cn' field should refer to the fully qualified public -hostname of the server. For the SAN extension data, there -must also be one or more 'dns_name' fields that contain all -possible hostnames that can be reasonably used by clients -to reach the server, both with and without domain name -qualifiers. If clients are likely to connect to the server -by IP address, then one or more 'ip_address' fields should -also be added. -

      -

      -Use the template file as input to a certtool -command to sign the server certificate: -

      - 
      -certtool --generate-certificate --load-privkey serverkey.pem \
-  --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
-  --template server.info --outfile servercert.pem
-
      -

      -This gives two files: -

      -
        -
      • serverkey.pem - The server's private key. -
        • -
      • servercert.pem - The server's public key. -
        • -
      -

      -We can examine this certificate and its signature: -

      - 
      certtool -i --infile servercert.pem
-X.509 certificate info:
-
-Version: 3
-Serial Number (hex): 00
-Subject: O=Libvirt Project,CN=compute1.libvirt.org
-Issuer: CN=Libvirt Project
-Signature Algorithm: RSA-SHA
-Validity:
-        Not Before: Wed Oct 04 09:09:44 UTC 2017
-        Not After: Thu Oct 04 09:09:44 UTC 2018
-Extensions:
-        Basic Constraints (critical):
-                Certificate Authority (CA): FALSE
-        Subject Alternative Name (not critical):
-                DNSname: compute1
-                DNSname: compute1.libvirt.org
-                IPAddress: 10.0.0.74
-                IPAddress: 192.168.1.24
-                IPAddress: 2001:cafe::74
-                IPAddress: fe20::24
-
      -

      -Note the "Issuer" CN is "Libvirt Project" (the CA) and -the "Subject" CN is "compute1.libvirt.org" (the server). -Notice that the hostname listed in the CN must also -be duplicated as a DNSname entry -

      -

      -Finally we have two files to install: -

      -
        -
      • serverkey.pem is -the server's private key which should be copied to the -server only as -/etc/pki/libvirt/private/serverkey.pem. -
        • -
      • servercert.pem is the server's certificate -which can be installed on the server as -/etc/pki/libvirt/servercert.pem. -
        • -
      -

      - Issuing client certificates -

      -

      -For each client (ie. any program linked with libvirt, such as -virt-manager) -you need to issue a certificate with the X.509 Distinguished Name (DN) -set to a suitable name. You can decide this on a company / organisation -policy. For example: -

      - 
      -C=GB,ST=London,L=London,O=Libvirt Project,CN=name_of_client
-
      -

      -The process is the same as for -setting up the -server certificate so here we just briefly cover the -steps. -

      -
        -
      1. -Make a private key: -
        -certtool --generate-privkey > clientkey.pem
-
        -
        2. -
      2. -Act as CA and sign the certificate. Create client.info containing: -
        -country = GB
-state = London
-locality = London
-organization = Libvirt Project
-cn = client1
-tls_www_client
-encryption_key
-signing_key
-
        -and sign by doing: -
        -certtool --generate-certificate --load-privkey clientkey.pem \
-  --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
-  --template client.info --outfile clientcert.pem
-
        -
        3. -
      3. -Install the certificates on the client machine: -
        -cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem
-cp clientcert.pem /etc/pki/libvirt/clientcert.pem
-
        -
        4. -
      -

      - Troubleshooting TLS certificate problems -

      -
      -
      failed to verify client's certificate
      -
      -

      -On the server side, run the libvirtd server with -the '--listen' and '--verbose' options while the -client is connecting. The verbose log messages should -tell you enough to diagnose the problem. -

      -
      -
      -

      You can use the virt-pki-validate shell script -to analyze the setup on the client or server machines, preferably as root. -It will try to point out the possible problems and provide solutions to -fix the set up up to a point where you have secure remote access.

      - - diff --git a/docs/tlscerts.rst b/docs/tlscerts.rst new file mode 100644 index 0000000000..c86362974c --- /dev/null +++ b/docs/tlscerts.rst @@ -0,0 +1,331 @@ +========================== +TLS x509 certificate setup +========================== + +.. contents:: + +Public Key Infrastructure set up +-------------------------------- + +If you are unsure how to create TLS certificates, skip to the next section. + +.. list-table:: + :header-rows: 1 + + * - Location + - Machine + - Description + - Required fields + + * - ``/etc/pki/CA/cacert.pem`` + - Installed on the client and server + - CA's certificate + - n/a + + * - ``$HOME/.pki/cacert.pem`` + - Installed on the client + - CA's certificate + - n/a + + * - ``/etc/pki/libvirt/private/serverkey.pem`` + - Installed on the server + - Server's private key + - n/a + + * - ``/etc/pki/libvirt/servercert.pem`` + - Installed on the server + - Server's certificate signed by the CA + - CommonName (CN) must be the hostname of the server as it is seen by + clients. All hostname and IP address variants that might be used to + reach the server should be listed in Subject Alt Name fields. + + * - ``/etc/pki/libvirt/private/clientkey.pem`` + - Installed on the client + - Client's private key + - n/a + + * - ``/etc/pki/libvirt/clientcert.pem`` + - Installed on the client + - Client's certificate signed by the CA + - Distinguished Name (DN) can be checked against an access control list + (``tls_allowed_dn_list``). + + * - ``$HOME/.pki/libvirt/clientkey.pem`` + - Installed on the client + - Client's private key + - n/a + + * - ``$HOME/.pki/libvirt/clientcert.pem`` + - Installed on the client + - Client's certificate signed by the CA + (`more info <#Remote_TLS_client_certificates>`__) + - Distinguished Name (DN) can be checked against an access control list + (``tls_allowed_dn_list``). + +If 'pkipath' is specified in URI, then all the client certificates must be found +in the path specified, otherwise the connection will fail with a fatal error. If +'pkipath' is not specified: + +- For a non-root user, libvirt tries to find the certificates in + $HOME/.pki/libvirt first. If the required CA certificate cannot be found, + then the global default location (/etc/pki/CA/cacert.pem) will be used. + Likewise, if either the client certificate or the client key cannot be found, + then the global default locations (/etc/pki/libvirt/clientcert.pem, + /etc/pki/libvirt/private/clientkey.pem) will be used. + +- For the root user, the global default locations will always be used. + +Background to TLS certificates +------------------------------ + +Libvirt supports TLS certificates for verifying the identity of the server and +clients. There are two distinct checks involved: + +- The client should know that it is connecting to the right server. Checking + done by client by matching the certificate that the server sends to the + server's hostname. May be disabled by adding ``?no_verify=1`` to the `remote + URI `__. + +- The server should know that only permitted clients are connecting. This can + be done based on client's IP address, or on client's IP address and client's + certificate. Checking done by the server. May be enabled and disabled in the + `libvirtd.conf file `__. + +For full certificate checking you will need to have certificates issued by a +recognised `Certificate Authority +(CA) `__ for your server(s) +and all clients. To avoid the expense of getting certificates from a commercial +CA, you can set up your own CA and tell your server(s) and clients to trust +certificates issues by your own CA. Follow the instructions in the next section. + +Be aware that the `default configuration for +libvirtd `__ allows any client to +connect provided they have a valid certificate issued by the CA for their own IP +address. You may want to change this to make it less (or more) permissive, +depending on your needs. + +Setting up a Certificate Authority (CA) +--------------------------------------- + +You will need the `GnuTLS certtool program documented +here `__. In +Fedora, it is in the ``gnutls-utils`` package. + +Create a private key for your CA: + +:: + + certtool --generate-privkey > cakey.pem + +and self-sign it by creating a file with the signature details called +``ca.info`` containing: + +:: + + cn = Name of your organization + ca + cert_signing_key + +:: + + certtool --generate-self-signed --load-privkey cakey.pem \ + --template ca.info --outfile cacert.pem + +(You can delete ``ca.info`` file now if you want). + +Now you have two files which matter: + +- ``cakey.pem`` - Your CA's private key (keep this very secret!) + +- ``cacert.pem`` - Your CA's certificate (this is public). + +``cacert.pem`` has to be installed on clients and server(s) to let them know +that they can trust certificates issued by your CA. + +The normal installation directory for ``cacert.pem`` is +``/etc/pki/CA/cacert.pem`` on all clients and servers. + +To see the contents of this file, do: + +:: + + certtool -i --infile cacert.pem + + X.509 certificate info: + + Version: 3 + Serial Number (hex): 00 + Subject: CN=Libvirt Project + Issuer: CN=Libvirt Project + Signature Algorithm: RSA-SHA + Validity: + Not Before: Mon Jun 18 16:22:18 2007 + Not After: Tue Jun 17 16:22:18 2008 + [etc] + +This is all that is required to set up your CA. Keep the CA's private key +carefully as you will need it when you come to issue certificates for your +clients and servers. + +Issuing server certificates +--------------------------- + +For each server (libvirtd) you need to issue a certificate containing one or +more hostnames and/or IP addresses. Historically the CommonName (CN) field would +contain the hostname of the server and would match the hostname used in the URI +that clients pass to libvirt. In most TLS implementations the CN field is +considered legacy data. The preferential mechanism is to use Subject Alt Name +(SAN) extension fields to validate against. In the future use of the CN field +for validation may be discontinued entirely, so it is strongly recommended to +include the SAN fields. + +In the example below, clients will be connecting to the server using a +`URI `__ of ``qemu://compute1.libvirt.org/system``, so the +CN must be "``compute1.libvirt.org``". + +Make a private key for the server: + +:: + + certtool --generate-privkey > serverkey.pem + +and sign that key with the CA's private key by first creating a template file +called ``server.info``. The template file will contain a number of fields to +define the server as follows: + +:: + + organization = Name of your organization + cn = compute1.libvirt.org + dns_name = compute1 + dns_name = compute1.libvirt.org + ip_address = 10.0.0.74 + ip_address = 192.168.1.24 + ip_address = 2001:cafe::74 + ip_address = fe20::24 + tls_www_server + encryption_key + signing_key + +The 'cn' field should refer to the fully qualified public hostname of the +server. For the SAN extension data, there must also be one or more 'dns_name' +fields that contain all possible hostnames that can be reasonably used by +clients to reach the server, both with and without domain name qualifiers. If +clients are likely to connect to the server by IP address, then one or more +'ip_address' fields should also be added. + +Use the template file as input to a ``certtool`` command to sign the server +certificate: + +:: + + certtool --generate-certificate --load-privkey serverkey.pem \ + --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \ + --template server.info --outfile servercert.pem + +This gives two files: + +- ``serverkey.pem`` - The server's private key. + +- ``servercert.pem`` - The server's public key. + +We can examine this certificate and its signature: + +:: + + certtool -i --infile servercert.pem + X.509 certificate info: + + Version: 3 + Serial Number (hex): 00 + Subject: O=Libvirt Project,CN=compute1.libvirt.org + Issuer: CN=Libvirt Project + Signature Algorithm: RSA-SHA + Validity: + Not Before: Wed Oct 04 09:09:44 UTC 2017 + Not After: Thu Oct 04 09:09:44 UTC 2018 + Extensions: + Basic Constraints (critical): + Certificate Authority (CA): FALSE + Subject Alternative Name (not critical): + DNSname: compute1 + DNSname: compute1.libvirt.org + IPAddress: 10.0.0.74 + IPAddress: 192.168.1.24 + IPAddress: 2001:cafe::74 + IPAddress: fe20::24 + +Note the "Issuer" CN is "Libvirt Project" (the CA) and the "Subject" CN is +"compute1.libvirt.org" (the server). Notice that the hostname listed in the CN +must also be duplicated as a DNSname entry + +Finally we have two files to install: + +- ``serverkey.pem`` is the server's private key which should be copied to the + server *only* as ``/etc/pki/libvirt/private/serverkey.pem``. + +- ``servercert.pem`` is the server's certificate which can be installed on the + server as ``/etc/pki/libvirt/servercert.pem``. + +Issuing client certificates +--------------------------- + +For each client (ie. any program linked with libvirt, such as +`virt-manager `__) you need to issue a certificate +with the X.509 Distinguished Name (DN) set to a suitable name. You can decide +this on a company / organisation policy. For example: + +:: + + C=GB,ST=London,L=London,O=Libvirt Project,CN=name_of_client + +The process is the same as for `setting up the server +certificate <#Remote_TLS_server_certificates>`__ so here we just briefly cover +the steps. + +#. Make a private key: + + :: + + certtool --generate-privkey > clientkey.pem + +#. Act as CA and sign the certificate. Create client.info containing: + + :: + + country = GB + state = London + locality = London + organization = Libvirt Project + cn = client1 + tls_www_client + encryption_key + signing_key + + and sign by doing: + + :: + + certtool --generate-certificate --load-privkey clientkey.pem \ + --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \ + --template client.info --outfile clientcert.pem + +#. Install the certificates on the client machine: + + :: + + cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem + cp clientcert.pem /etc/pki/libvirt/clientcert.pem + +Troubleshooting TLS certificate problems +---------------------------------------- + +failed to verify client's certificate + On the server side, run the libvirtd server with the '--listen' and + '--verbose' options while the client is connecting. The verbose log messages + should tell you enough to diagnose the problem. + +You can use the virt-pki-validate shell script to analyze the setup on the +client or server machines, preferably as root. It will try to point out the +possible problems and provide solutions to fix the set up up to a point where +you have secure remote access. -- 2.35.1 From nobody Fri May 10 15:26:10 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=1649084768; cv=none; d=zohomail.com; s=zohoarc; b=aF25Me0A2oOtYqEy7AKCyB7SrZNo7g9+SLyE5os31P39U20UG2HNURRrkKiYXhQ5J2EZrHGbIEQ35jnJS4FD+uJv9ltWadMEQ0t/fsT2ngx9SWjqzGvZ+sRi0R4LaG/z03Z8+u19MKCB1ySTlVFmGrWsKKXDnGlm7trUqs9bd4g= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649084768; 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=NBwvHicMDUEa4bmMt6SfHU6lNYO1pEULVikjIZCC0Io=; b=h6iay1YaIAEDcSqIwO5s1hDeUMDBvqp8MUNodq/D7fLkd42MGZ8PtspZsEt5/C4Ll6DwSrH2a3nQMMI2jZ19XsaxYT4cin6wkTiZUDXl8kIC+pwMstMVfFwcs/vh9WcNreAvkSLeyx7D/dnyky/Yu0B5uFnIyVCkTZpCovikxv4= 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 1649084768627441.2113567937081; Mon, 4 Apr 2022 08:06:08 -0700 (PDT) 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-182-3lI2kMVMNH2ebvfD0FaOOg-1; Mon, 04 Apr 2022 11:04:40 -0400 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 4F1CF100BAAE; Mon, 4 Apr 2022 15:04:32 +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 3B66BC28111; Mon, 4 Apr 2022 15:04:32 +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 578861940375; Mon, 4 Apr 2022 15:04:31 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 613061940364 for ; Mon, 4 Apr 2022 15:04:30 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 52E8914583E6; Mon, 4 Apr 2022 15:04:30 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id BC27014582FB for ; Mon, 4 Apr 2022 15:04:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649084767; 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=NBwvHicMDUEa4bmMt6SfHU6lNYO1pEULVikjIZCC0Io=; b=POej9zlKQd0GPmu8p9mWEw5yAXn29s/XuR29EcVk/AmUp3OXLodxJs+crlF9/gzHchf7eB w1HUSEMMhPvaKTPqWlVs0KU/to9itKpUynqA3stCyGU2nSYkViL5g7byti69MT4sXPMofc J4q47pK/MsBgzKDba7mE9vpAXakkeWw= X-MC-Unique: 3lI2kMVMNH2ebvfD0FaOOg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 4/7] docs: Move 'tlscerts' page to 'kbase/' Date: Mon, 4 Apr 2022 17:04:21 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 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: 1649084770790100002 Content-Type: text/plain; charset="utf-8"; x-default="true" Signed-off-by: Peter Krempa Reviewed-by: Pavel Hrdina --- docs/daemons.rst | 2 +- docs/docs.html.in | 3 --- docs/kbase/index.rst | 3 +++ docs/kbase/meson.build | 1 + docs/{ =3D> kbase}/tlscerts.rst | 0 docs/meson.build | 1 - docs/remote.html.in | 2 +- 7 files changed, 6 insertions(+), 6 deletions(-) rename docs/{ =3D> kbase}/tlscerts.rst (100%) diff --git a/docs/daemons.rst b/docs/daemons.rst index 383f0f64ff..2918b3d4ce 100644 --- a/docs/daemons.rst +++ b/docs/daemons.rst @@ -100,7 +100,7 @@ optionally, one or two TCP sockets: with full read-write privileges. A connection to this socket gives the client privileges that are equivalent to having a root shell. Access con= trol can be enforced either through validation of `x509 certificates - `__, and/or by enabling an `authentication mechanism + `__, and/or by enabling an `authentication mechanism `__. NB, some distros will use ``/run`` instead of ``/var/run``. diff --git a/docs/docs.html.in b/docs/docs.html.in index 225827b693..ff7a95fae7 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -28,9 +28,6 @@
      Remote access
      Enable remote access over TCP
      -
      TLS certs
      -
      Generate and deploy x509 certificates for TLS
      -
      Authentication
      Configure authentication for the libvirt daemon
      diff --git a/docs/kbase/index.rst b/docs/kbase/index.rst index 860bfde71f..9c4e921f1f 100644 --- a/docs/kbase/index.rst +++ b/docs/kbase/index.rst @@ -19,6 +19,9 @@ Usage Examination of the security protections used for QEMU and how they need configuring to allow use of QEMU passthrough with host files/devices. +`TLS certificates `__ + Generate and deploy x509 certificates for TLS. + `RPM deployment `__ Explanation of the different RPM packages and illustration of which to pick for installation diff --git a/docs/kbase/meson.build b/docs/kbase/meson.build index d632f9bda1..4114fc81d1 100644 --- a/docs/kbase/meson.build +++ b/docs/kbase/meson.build @@ -20,6 +20,7 @@ docs_kbase_files =3D [ 'secureusage', 'snapshots', 'systemtap', + 'tlscerts', 'virtiofs', ] diff --git a/docs/tlscerts.rst b/docs/kbase/tlscerts.rst similarity index 100% rename from docs/tlscerts.rst rename to docs/kbase/tlscerts.rst diff --git a/docs/meson.build b/docs/meson.build index 8b174fe41e..d738da85f2 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -109,7 +109,6 @@ docs_rst_files =3D [ 'testapi', 'testsuites', 'testtck', - 'tlscerts', ] # list of web targets to build for docs/web rule diff --git a/docs/remote.html.in b/docs/remote.html.in index 47fb2d4df3..3a5258a0d5 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -61,7 +61,7 @@ Remote libvirt supports a range of transports:
      TLS 1.0 (SSL 3.1) authenticated and encrypted TCP/IP socket, usually listening on a public port number. To use this you will need to - generate = client and + gen= erate client and server certificates. The standard port is 16514.
      --=20 2.35.1 From nobody Fri May 10 15:26:10 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=1649084684; cv=none; d=zohomail.com; s=zohoarc; b=hCLC1Rb+/ALDZPdZONBVK01IpdMo49DnCm1HgVslJp9rFA7ptBykM7gE0J5RyC6uzgPZfheIoYTQz/v5GeXdjK1pF1RkWO0yqAibs/8Vc1gNMgIaK4wYIDn1QqJIz6A0DYKO7M3ACR/W1BEgwHphLYzWgEsWGAbab5/b18KPqfo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649084684; 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=G29bV3rMMNxSWMSxrk1zMF5fLlDLQg89ftpSiEjcJH8=; b=BU+GTs074Nw0TD/WjDjzjp/fNRwscZhCr566BYminbeqHOnkoYMjt150tmVSFR96XCvVyFxrm4qBarzJ/5WLyH5RlbidBAXB3UTCyD75+f7foJT0d0F2LmGZMXhO0T4sit8MNBnQGBOU+MT0NRj5McYhEw5vWPUkzLYNAzNnErM= 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 164908468406462.37917017118684; Mon, 4 Apr 2022 08:04:44 -0700 (PDT) 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-542-GE7UYk3IOs2-Un_PvzBe-w-1; Mon, 04 Apr 2022 11:04:40 -0400 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 0A9728041A1; Mon, 4 Apr 2022 15:04:33 +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 D70FE416141; Mon, 4 Apr 2022 15:04:32 +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 AD9DA1940370; Mon, 4 Apr 2022 15:04:31 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 46D0E1940367 for ; Mon, 4 Apr 2022 15:04:31 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 3CC5214582FB; Mon, 4 Apr 2022 15:04:31 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id BCD2214583D1 for ; Mon, 4 Apr 2022 15:04:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649084682; 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=G29bV3rMMNxSWMSxrk1zMF5fLlDLQg89ftpSiEjcJH8=; b=dtejbgl0pLxDo1P7PgbOxBwFf3O4krMLEfzE5NdDv+gE7kkyTUnjYTtD4i9nGAVOKCz6cD tZjMh/RwJE9IJhwG5Ky4v+hfu/Wg0u+8K+BazLZztd9Gi75nLNn2lfqDG3+b6NAN8fvYKE fo96wrpFSgYnmZ4UWKc827JMRZ7Xj0Y= X-MC-Unique: GE7UYk3IOs2-Un_PvzBe-w-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 5/7] docs: convert 'windows' page to rst Date: Mon, 4 Apr 2022 17:04:22 +0200 Message-Id: <1ee4671bc051b7d16226bffa6f28e11a180c8754.1649084492.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 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: 8bit Content-Type: application/octet-stream; x-default=true X-Zoho-Virus-Status: 1 X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649084685997100005 From: Pavel Hrdina Signed-off-by: Pavel Hrdina Signed-off-by: Peter Krempa --- docs/meson.build | 2 +- docs/windows.html.in | 194 ------------------------------------------- docs/windows.rst | 139 +++++++++++++++++++++++++++++++ 3 files changed, 140 insertions(+), 195 deletions(-) delete mode 100644 docs/windows.html.in create mode 100644 docs/windows.rst diff --git a/docs/meson.build b/docs/meson.build index d738da85f2..f54b56ed01 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_html_in_files = [ 'remote', 'storage', 'uri', - 'windows', ] docs_rst_files = [ @@ -109,6 +108,7 @@ docs_rst_files = [ 'testapi', 'testsuites', 'testtck', + 'windows', ] # list of web targets to build for docs/web rule diff --git a/docs/windows.html.in b/docs/windows.html.in deleted file mode 100644 index 0f2d9061c4..0000000000 --- a/docs/windows.html.in +++ /dev/null @@ -1,194 +0,0 @@ - - - - -

      Windows support

      - -
        - -

        - Libvirt is known to work as a client (not server) on Windows XP - (32-bit), and Windows 7 (64-bit). Other Windows variants likely work - as well but we either haven't tested or received reports for them. -

        - -

        Installation packages

        - -

        - Users who need pre-built Windows DLLs of libvirt are advised - to use the Virt Viewer - pre-compiled Windows MSI packages -

        - -

        - These installers include the libvirt, gtk-vnc and spice-gtk DLLs - along with any of their pre-requisite supporting DLLs, the virsh - command line tool and the virt-viewer & remote-viewer graphical - tools. The development headers are not currently provided in this - installer, so this cannot be used for compiling new applications - against libvirt. -

        - -

        Connection types

        - -

        - These connection types are known to work: -

        - -
          -
        • QEMU with TLS (qemu+tls://)
          • -
        • QEMU with direct TCP (qemu+tcp://)
          • -
        • VMware ESX (esx://)
          • -
        • VMware VPX (vpx://)
          • -
        - -

        - These connection types are known not to work: -

        - -
          -
        • QEMU with SSH (qemu+ssh://)
          • -
        - -

        - All other connection types may or may not work, and haven't been - tested. -

        - -

        - Please let us know either the results (either way) if you do. -

        - -

        - Special note - Support for VirtualBox *on windows* was added in - libvirt 0.8.7, so reports on success and failure if you're using that - would be really helpful and appreciated. -

        - -

        - WARNING - The qemu+tcp:// connection type passes all traffic - without encryption. This is a security hazard, and should not - be used in security sensitive environments. -

        - -

        Connecting to VMware ESX/vSphere

        - -

        - Details on the capabilities, certificates, and connection string - syntax used for connecting to VMware ESX and vSphere can be found - online here:
        -

        - - https://libvirt.org/drvesx.html - -

        TLS Certificates

        - -

        - TLS certificates need to have been created and placed in the correct - locations, before you will be able to connect to QEMU servers over - TLS. -

        - -

        - Information on generating TLS certificates can be found here: -

        - - https://wiki.libvirt.org/page/TLSSetup - -

        - These instructions are for *nix, and have not yet been adapted for - Windows. You'll need to figure out the Windows equivalents until - that's done (sorry). If you can help us out with this, that would be - really welcome. -

        - -

        - The locations of the TLS certificates and key file on Windows are hard - coded, rather than being configurable. -

        - -

        - The Certificate Authority (CA) certificate file must be placed in: -

        - -
          -
        • %APPDATA%\libvirt\pki\CA\cacert.pem
          • -
        - -

        - The Client certificate file must be placed in: -

        - -
          -
        • %APPDATA%\libvirt\pki\libvirt\clientcert.pem
          • -
        - -

        - The Client key file must be placed in: -

        - -
          -
        • %APPDATA%\libvirt\pki\libvirt\private\clientkey.pem
          • -
        - -

        - On an example Windows 7 x64 system here, this resolves to these paths: -

        - -
          -
        • C:\Users\someuser\AppData\Roaming\libvirt\pki\CA\cacert.pem
          • -
        • C:\Users\someuser\AppData\Roaming\libvirt\pki\libvirt\clientcert.pem
          • -
        • C:\Users\someuser\AppData\Roaming\libvirt\pki\libvirt\private\clientkey.pem
          • -
        - -

        Feedback

        - -

        - Feedback and suggestions on changes to make and what else to include - are desired. -

        - -

        Compiling yourself

        - -

        - Libvirt can be compiled on Windows using the free - MinGW compiler. -

        - -

        MSYS Build script

        - -

        - The easiest way is to use the msys_setup script, developed by - Matthias Bolte. This is actively developed and kept current with - libvirt releases: -

        - - https://github.com/photron/msys_setup - -

        Cross compiling

        - -

        - You can also cross-compile to a Windows target from a Fedora machine - using the packages available in the Fedora repos. -

        - -

        By hand

        - -

        - Use these options when following the instructions on the - Compiling page. -

        - -
        -meson build \
-  -Dsasl=disabled \
-  -Dpolkit=disabled \
-  -Ddriver_libxl=disabled \
-  -Ddriver_qemu=disabled \
-  -Ddriver_lxc=disabled \
-  -Ddriver_openvz=disabled \
-  -Ddriver_libvirtd=disabled
-
        - - - diff --git a/docs/windows.rst b/docs/windows.rst new file mode 100644 index 0000000000..5bfc2fa5ba --- /dev/null +++ b/docs/windows.rst @@ -0,0 +1,139 @@ +=============== +Windows support +=============== + +.. contents:: + +Libvirt is known to work as a client (not server) on Windows XP (32-bit), and +Windows 7 (64-bit). Other Windows variants likely work as well but we either +haven't tested or received reports for them. + +Installation packages +--------------------- + +Users who need pre-built Windows DLLs of libvirt are advised to use the `Virt +Viewer `__ pre-compiled `Windows MSI +packages `__ + +These installers include the libvirt, gtk-vnc and spice-gtk DLLs along with any +of their pre-requisite supporting DLLs, the virsh command line tool and the +virt-viewer & remote-viewer graphical tools. The development headers are not +currently provided in this installer, so this cannot be used for compiling new +applications against libvirt. + +Connection types +---------------- + +These connection types are known to work: + +- QEMU with TLS (qemu+tls://) + +- QEMU with direct TCP (qemu+tcp://) + +- VMware ESX (esx://) + +- VMware VPX (vpx://) + +These connection types are known not to work: + +- QEMU with SSH (qemu+ssh://) + +All other connection types may or may not work, and haven't been tested. + +Please let us know either the results (either way) if you do. + +**Special note** - Support for VirtualBox \*on windows\* was added in libvirt +0.8.7, so reports on success and failure if you're using that would be really +helpful and appreciated. + +**WARNING - The qemu+tcp:// connection type passes all traffic without +encryption. This is a security hazard, and should not be used in security +sensitive environments.** + +Connecting to VMware ESX/vSphere +-------------------------------- + +Details on the capabilities, certificates, and connection string syntax used for +connecting to VMware ESX and vSphere can be found online here: + +https://libvirt.org/drvesx.html + +TLS Certificates +---------------- + +TLS certificates need to have been created and placed in the correct locations, +before you will be able to connect to QEMU servers over TLS. + +Information on generating TLS certificates can be found here: + +https://wiki.libvirt.org/page/TLSSetup + +These instructions are for \*nix, and have not yet been adapted for Windows. +You'll need to figure out the Windows equivalents until that's done (sorry). If +you can help us out with this, that would be really welcome. + +The locations of the TLS certificates and key file on Windows are hard coded, +rather than being configurable. + +The Certificate Authority (CA) certificate file must be placed in: + +- %APPDATA%\libvirt\pki\CA\cacert.pem + +The Client certificate file must be placed in: + +- %APPDATA%\libvirt\pki\libvirt\clientcert.pem + +The Client key file must be placed in: + +- %APPDATA%\libvirt\pki\libvirt\private\clientkey.pem + +On an example Windows 7 x64 system here, this resolves to these paths: + +- C:\Users\someuser\AppData\Roaming\libvirt\pki\CA\cacert.pem + +- C:\Users\someuser\AppData\Roaming\libvirt\pki\libvirt\clientcert.pem + +- C:\Users\someuser\AppData\Roaming\libvirt\pki\libvirt\private\clientkey.pem + +Feedback +-------- + +Feedback and suggestions on changes to make and what else to include `are +desired `__. + +Compiling yourself +------------------ + +Libvirt can be compiled on Windows using the free `MinGW +compiler `__. + +MSYS Build script +~~~~~~~~~~~~~~~~~ + +The easiest way is to use the **msys_setup** script, developed by Matthias +Bolte. This is actively developed and kept current with libvirt releases: + +https://github.com/photron/msys_setup + +Cross compiling +~~~~~~~~~~~~~~~ + +You can also cross-compile to a Windows target from a Fedora machine using the +packages available in the Fedora repos. + +By hand +~~~~~~~ + +Use these options when following the instructions on the +`Compiling `__ page. + +:: + + meson build \ + -Dsasl=disabled \ + -Dpolkit=disabled \ + -Ddriver_libxl=disabled \ + -Ddriver_qemu=disabled \ + -Ddriver_lxc=disabled \ + -Ddriver_openvz=disabled \ + -Ddriver_libvirtd=disabled -- 2.35.1 From nobody Fri May 10 15:26:10 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=1649084687; cv=none; d=zohomail.com; s=zohoarc; b=cuVA9H0kfxac1QlxLSDfDFg33gNvbdmeZ0wXhzW4Zv8ruhgOmiAOSqOBnBVTJ95p+4Y01NQENhRYbRRtDJTghhMB99tYgYUYaydKJau7pNRk4Oi9GlIHYpbU7V7pMckoWArtrJiQgf/P7tes2HzNA5PfsXrlqHrlmrAKtS+I090= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649084687; 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=BjQF9ddXmaPpGE0NalwE0VrqLqzkzN6q1HXbY3T3POg=; b=ItywXhIULEntcIqQ4KWarIiPcoPoI1wItlcb4RRF3pzxuZ+u3zn5y5v4O5pI20G0NTj/EmSZVGtNxZWYzTL68gIjwMPZ3UfXmk76Zq9oklgTPdFD84j8JujwrwdykWiZqdilbpG5pZy1jJEGpXVVSUqBxWmPNaAVbY6y+LqOuAo= 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 1649084687025132.64082158746123; Mon, 4 Apr 2022 08:04:47 -0700 (PDT) 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-203-HkT8mgAfOi-oieqn3ZrmPA-1; Mon, 04 Apr 2022 11:04:44 -0400 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 74C55805F68; Mon, 4 Apr 2022 15:04:33 +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 53A52400E875; Mon, 4 Apr 2022 15:04:33 +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 0E8C51940367; Mon, 4 Apr 2022 15:04:33 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 88F341940364 for ; Mon, 4 Apr 2022 15:04:32 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 7CB3314583D1; Mon, 4 Apr 2022 15:04:32 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id A3C2414583CB for ; Mon, 4 Apr 2022 15:04:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649084685; 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=BjQF9ddXmaPpGE0NalwE0VrqLqzkzN6q1HXbY3T3POg=; b=XnSLDNpIg7MgllWlDqZnX5u8m/zzbqlkIHZrM44yaakHiUzkj15xqlobpH8nZhoLQK6Zpz oQcFB2diEqreZQAbXnUUbC3Puc8gmlnxw9y4mcGRkMUf2jJfQQZQw3JcvN7W784D+cHTcE 6BeqPUq8TsBAQ8L8+c4G9zJvEEBaA9s= X-MC-Unique: HkT8mgAfOi-oieqn3ZrmPA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 6/7] docs: csharp: Remove project-specific information Date: Mon, 4 Apr 2022 17:04:23 +0200 Message-Id: <73c4624c60e0267971fd157d8b27b3e226fb38ad.1649084492.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 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-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649084688259100001 The enumeration of functions and types supported by the bindings was moved to the 'README.rst' file in the 'libvirt-csharp' repo: https://gitlab.com/libvirt/libvirt-csharp/-/merge_requests/8 Remove the corresponding bits from the main repository. Signed-off-by: Peter Krempa Reviewed-by: Pavel Hrdina --- docs/csharp.html.in | 418 -------------------------------------------- 1 file changed, 418 deletions(-) diff --git a/docs/csharp.html.in b/docs/csharp.html.in index 257637495d..f94c08ff8d 100644 --- a/docs/csharp.html.in +++ b/docs/csharp.html.in @@ -40,55 +40,6 @@ git clone https://gitlab.com/libvirt/libvirt-csharp.git -

        Usage

        - -

        - The libvirt C# bindings class library exposes the Libvirt - namespace. This namespace exposes all of the needed types (enum, - struct), plus many classes exposing the libvirt API methods. -

        -

        - These classes are grouped into functional areas, with each class - exposing libvirt methods related to that area. -

        -

        - For example, the libvirt methods related to connections, such as - virConnectOpenAuth and virConnectNumOfDomains, are in - the Connect class. -
        - They are accessed as Connect.OpenAuth, and - Connect.NumOfDomains respectively. -

        -

        - In the same manner, the other class name mappings are: -

        - - - - - - - - - - - -
        Name of libvirt functionC# class name
        virDomain...Domain
        virEvent...Event
        virInterface...Interface
        virNetwork...Network
        virNode...Node
        virSecret...Secret
        virStoragePool...StoragePool
        virStorageVolume...StorageVolume
        virStream...Stream
        -

        - There are some additions as well: -

        -
          -
        • - There is a class named Library, exposing the - virGetVersion and virInitialize methods -
          • -
        • - There is a class named Errors, exposing the error - related methods. For example, virSetErrorFunc and - virConnResetLastError. -
          • -
        -

        Authors

        @@ -97,374 +48,5 @@ git clone https://gitlab.com/libvirt/libvirt-csharp.git based upon the previous work of Jarom=C3=ADr =C4=8Cervenka.

        -

        Test Configuration

        - -

        - Testing is performed using the following configurations: -

        -
          -
        • Windows 7 (64 bits) / .Net 4
          • -
        • Windows 7 (64 bits) / Mono 2.6.7 (compiled in 32 bits)
          • -
        • Ubuntu 10.10 amd64 / Mono 2.6.7 (compiled in 64 bits)
          • -
        - -

        Type Coverage

        - -

        - Coverage of the libvirt types is: -

        - - - - - virConnectOpenAuth - - - - <= /tr> - - - = - - - - = - - - = - No - - - - - - - = - - - virConnectSetErrorFunc, virDomainStats - Yes - - - - - - <= td> - - - - <= td> - = - - - = - = - - - - <= td> - - - - - - - - - - - - - <= td> - - - - = - <= td> - = -
        TypeNameBinding?Tested?S= ample Code?Works?Tested .Net/Windows Works?Teste= d Mono (32-bit)/Windows Works?Tested Mono (64-bit)/Linux Works?
        enumvirCPUCompareResultNo
        structvirConnectYes, an IntPtr as the stru= ct is not publicYesYes
        structvirConnectAuthYesYesYesYesYesYes
        structvirConnectCredentialYesYes<= /td>virConnectOpenAuthYesYesYesYes<= /td>
        enumvirConnectCredentialTypeYesYe= svirConnectOpenAuthYesYesYesYe= s
        enumvirConnectFlagsNo
        structvirDomainYes, an IntPtr as the struc= t is not public
        structvirDomainBlockInfoNo
        structvirDomainBlockStatsInfoYesY= esvirDomainStatsYesYesYesYes
        enumvirDomainCoreDumpFlagsNo
        enumvirDomainCreateFlagsNo
        enumvirDomainDeviceModifyFlagsNo<= /td>
        enumvirDomainEventDefinedDetailTypeYesYesvirEventRegisterImplYesYesYesYes
        structvirDomainEventGraphicsAddressNo
        enumvirDomainEventGraphicsAddressTypeNo
        enumvirDomainEventGraphicsPhaseNo=
        structvirDomainEventGraphicsSubjectNo
        structvirDomainEventGraphicsSubjectIdentity
        enumvirDomainEventIDNo
        enumvirDomainEventIOErrorActionNo=
        enumvirDomainEventResumedDetailTypeYesYesvirEventRegisterImplYesYesYesYes
        enumvirDomainEventStartedDetailTypeYesYesvirEventRegisterImplYesYesYesYes
        enumvirDomainEventStoppedDetailTypeYesYesvirEventRegisterImplYesYesYesYes
        enumvirDomainEventSuspendedDetailTypeYesYesvirEventRegisterImplYesYesYes= Yes
        enumvirDomainEventTypeYesYesvirEventRegisterImplYesYesYesYes
        enumvirDomainEventUndefinedDetailTypeYesYesvirEventRegisterImplYesYesYes= Yes
        enumvirDomainEventWatchdogActionNo
        structvirDomainInfoYesYesYesYesYes= Yes
        structvirDomainInterfaceStatsStructYesYesvirDomainStatsYesYesYes
        structvirDomainJobInfoNo=
        enumvirDomainJobTypeNo
        enumvirDomainMemoryFlagsNo
        structvirDomainMemoryStatStructNo=
        enumvirDomainMemoryStatTagsYesNo<= /td>Maybe
        enumvirDomainMigrateFlagsNo
        structvirDomainSnapshotNo
        enumvirDomainSnapshotDeleteFlags<= /td>
        enumvirDomainStateYesYes= Yes
        enumvirDomainXMLFlagsYesYesYes
        enumvirEventHandleTypeYesYesvirEventRegisterImplYesYesYesYes
        structvirInterfaceYes, an IntPtr as the st= ruct is not public
        enumvirInterfaceXMLFlagsNo
        structvirNWFilterNo
        structvirNetworkYes, an IntPtr as the stru= ct is not public
        structvirNodeDeviceYes, an IntPtr as the s= truct is not public
        structvirNodeInfoYesNoMaybe
        structvirSchedParameterNo
        enumvirSchedParameterTypeNo
        structvirSecretNo
        enumvirSecretUsageTypeNo=
        structvirSecurityLabelNo=
        structvirSecurityModelNo=
        enumvirStoragePoolBuildFlagsYesNo= Maybe
        enumvirStoragePoolDeleteFlagsYesN= oMaybe
        structvirStoragePoolInfoYesYesYes
        structvirStoragePoolYes, an IntPtr as the = struct is not public<= /td>
        enumvirStoragePoolStateYesYesYes
        structvirStorageVolYes, an IntPtr as the s= truct is not public
        enumvirStorageVolDeleteFlagsNo
        structvirStorageVolInfoYesYesYes
        enumvirStorageVolTypeYesYesYes
        structvirStreamNo
        enumvirStreamEventTypeNo=
        enumvirStreamFlagsNo
        structvirVcpuInfoNo
        enumvirVcpuStateNo
        structvirErrorYesYesvirC= onnectSetErrorFunc, virDomainStatsYesYesYesYes
        - -

        - -

        Function Coverage

        - -

        - Coverage of the libvirt functions is: -

        - - - - - - - - - - - - - delegate - - - - - - = - - <= td>Yes - - No - - - - - - - - - - - <= td>Yes - Yes - - - - = - - - - - = - <= td>No - - Yes - - Yes - = Yes - - - - <= td> - - = - = - - - - - - - - - - = - <= td> - - - - <= td> - - - - - - - - - - - - <= td> - - = - - Yes - - - Yes - - - - - <= td> - - - - - - - - - - - - - - No - - - - - <= td> - - - - = - <= td> - - - - - <= td> - - - Yes - - Yes - <= td>Yes - Yes<= td>Yes - Yes - <= td>Yes - - <= td> - <= td> - = - - - - - - - - - - - - - - - = - = - - - - - - - - - - - - = - - No - - - <= td> - Yes - - - - - - - - - - - - - <= td> - - - Yes - - <= td>Yes - - - - = - - - <= td> - - - - = - - - - - - - <= td> - - - = - - - <= td> - <= td> - - - No - Yes - - - - = - No - - - - - Yes - - = - <= td>Yes - = - = - - - = - - - = - - - = - - - <= td>No - - - - - Yes - Yes - <= td>Yes - <= td>Yes - - <= td> - - - - - - - - - - - - - - <= td> - - - Yes - virConnectSetErrorFunc, virDomainInfos -
        NameBinding?Type?Tested?= Sample Code?Working?Tested .Net/Windows Works?Te= sted Mono (32-bit)/Windows Works?Tested Mono (64-bit)/Linux Works?=
        virConnectAuthCallbackYesdelegate= YesvirConnectOpenAuthYesYesYes= Yes
        virConnectBaselineCPUNofunction
        virConnectCloseYesfunctionYesvirConnectOpenAuthYesYesYesYes
        virConnectCompareCPUNofunction
        virConnectDomainEventCallbackYesdelegateYesYes
        virConnectDomainEventDeregisterNofunction<= /td>
        virConnectDomainEventDeregisterAnyNofuncti= on
        virConnectDomainEventGenericCallbackNodele= gate
        virConnectDomainEventGraphicsCallbackNodel= egate
        virConnectDomainEventIOErrorCallbackNodele= gate
        virConnectDomainEventIOErrorReasonCallbackNo
        virConnectDomainEventRTCChangeCallbackNode= legate
        virConnectDomainEventRegisterYesfunctionYesvirEventRegisterImplYesYesYes= Yes
        virConnectDomainEventRegisterAnyNofunction=
        virConnectDomainEventWatchdogCallbackNodel= egate
        virConnectDomainXMLFromNativeNofunction
        virConnectDomainXMLToNativeNofunction
        virConnectFindStoragePoolSourcesNofunction=
        virConnectGetCapabilitiesYesfunctionYes
        virConnectGetHostnameYesfunctionY= es
        virConnectGetLibVersionYesfunctionMaybe
        virConnectGetMaxVcpusYesfunctionN= oMaybe
        virConnectGetTypeYesfunctionNoMaybe
        virConnectGetURIYesfunctionYesYes
        virConnectGetVersionYesfunctionNo= Maybe
        virConnectIsEncryptedYesfunctionN= oMaybe
        virConnectIsSecureYesfunctionNoMaybe
        virConnectListDefinedDomainsYesfunctionYesvirConnectOpenAuthYesYesYesYes
        virConnectListDefinedInterfaces Yesfunctio= nYesYes
        virConnectListDefinedNetworksYesfunctionYesYes
        virConnectListDefinedStoragePoolsYesfuncti= onYesYes
        virConnectListDomainsYesfunctionY= esvirConnectOpenAuth, virDomainInfosYesYesYes
        virConnectListInterfacesYesfunctionYes, if the host handle the method=
        virConnectListNWFilters Nofunction
        virConnectListNetworksYesfunction= YesYes
        virConnectListSecretsYesfunctionN= oMaybe
        virConnectListStoragePoolsYesfunctionYesvirConnectOpenYesYesYes= Yes
        virConnectNumOfDefinedDomainsYesfunctionYesvirConnectOpenAuthYesYesYesYes
        virConnectNumOfDefinedInterfacesYesfunctio= nNoMaybe
        virConnectNumOfDefinedNetworksYesfunction<= /td>YesYes
        virConnectNumOfDefinedStoragePoolsYesfunct= ionYesYes
        virConnectNumOfDomainsYesfunction= YesvirConnectOpenAuth, virDomainInfosYesYesYesYes
        virConnectNumOfInterfacesYesfunctionMaybe
        virConnectNumOfNWFiltersNofunction
        virConnectNumOfNetworks YesfunctionYes
        virConnectNumOfSecretsYesfunction= NoMaybe
        virConnectNumOfStoragePoolsYesfunctionYesvirConnectOpenYesYesYes
        virConnectOpenYesfunctionYesvirConnectOpen, virEventRegisterImpl, virDomainInfosYesYesYes
        virConnectOpenAuthYesfunctionYes<= /td>virConnectOpenAuthYesYesYesYes<= /td>
        virConnectOpenReadOnlyYesfunction= NoMaybe
        virConnectRefYesfunctionNoMaybe
        virDomainAbortJobNofunction
        virDomainAttachDeviceYesfunctionN= oMaybe
        virDomainAttachDeviceFlagsYesfunctionNoMaybe
        virDomainBlockPeekNofunction
        virDomainBlockStatsYesfunctionYes= virDomainInfosYesYesYesYes
        virDomainCoreDumpYesfunctionNoMaybe
        virDomainCreateYesfunctionYesYes
        virDomainCreateLinuxNofunction
        virDomainCreateWithFlagsNofunction
        virDomainCreateXMLYesfunctionNoMaybe
        virDomainDefineXMLYesfunctionYes<= /td>Yes
        virDomainDestroyYesfunctionYesYes
        virDomainDetachDeviceYesfunctionN= oMaybe
        virDomainDetachDeviceFlagsYesfunctionNoMaybe
        virDomainFreeYesfunctionYesYes
        virDomainGetAutostartYesfunctionN= oMaybe
        virDomainGetBlockInfoNofunction
        virDomainGetConnectYesfunctionNo<= /td>Maybe
        virDomainGetIDYesfunctionNoMaybe
        virDomainGetInfoYesfunctionYesvirDomainInfosYesYesYesYes
        virDomainGetJobInfoNofunction
        virDomainGetMaxMemoryYesfunctionN= oMaybe
        virDomainGetMaxVcpusYesfunctionNo= Maybe
        virDomainGetNameYesfunctionYesvirConnectOpenAuth, virDomainInfosYesYesYe= sYes
        virDomainGetOSTypeYesfunctionNoMaybe
        virDomainGetSchedulerParametersNofunction<= /td>
        virDomainGetSchedulerTypeNofunction
        virDomainGetSecurityLabelNofunction
        virDomainGetUUIDYesfunctionNoMaybe
        virDomainGetUUIDStringYesfunction= NoMaybe
        virDomainGetVcpusNofunction
        virDomainGetXMLDescYesfunctionYes= virDomainInfosYesYesYesYes
        virDomainHasCurrentSnapshotNofunction
        virDomainHasManagedSaveImageNofunction
        virDomainInterfaceStats NofunctionvirDomainInfosYesYesYesYes=
        virDomainIsActiveYesfunctionYesYes
        virDomainIsPersistentYesfunctionN= oMaybe
        virDomainLookupByIDYesfunctionYes= virConnectOpenAuth, virDomainInfosYesYesYes
        virDomainLookupByNameYesfunctionY= esvirDomainInfosYesYesYesYes
        virDomainLookupByUUIDYesfunctionN= oMaybe
        virDomainLookupByUUIDStringYesfunctionNoMaybe
        virDomainManagedSave Nofunction
        virDomainManagedSaveRemoveNofunction
        virDomainMemoryPeekNofunction
        virDomainMemoryStatsNofunction
        virDomainMigrateNofunction
        virDomainMigrateSetMaxDowntimeNofunction
        virDomainMigrateToURI Nofunction
        virDomainPinVcpuNofunction
        virDomainRebootYesfunctionYesYes
        virDomainRef YesfunctionNoMaybe
        virDomainRestoreYes functionNoMaybe
        virDomainResume YesfunctionYesYes
        virDomainRevertToSnapshotNofunction
        virDomainSaveYesfunctionNoMaybe
        virDomainSetAutostartYesfunctionN= oMaybe
        virDomainSetMaxMemory YesfunctionMaybe
        virDomainSetMemoryYesfunctionNoMaybe
        virDomainSetSchedulerParametersNofunction<= /td>
        virDomainSetVcpusYesfunctionNoMaybe
        virDomainShutdownYesfunctionYesYes
        virDomainSnapshotCreateXMLNofunction
        virDomainSnapshotCurrentNofunction
        virDomainSnapshotDeleteNofunction=
        virDomainSnapshotFreeNofunction
        virDomainSnapshotGetXMLDescNofunction
        virDomainSnapshotListNamesNofunction
        virDomainSnapshotLookupByNameNofunction
        virDomainSnapshotNumNofunction
        virDomainSuspendYesfunctionYesYes
        virDomainUndefineYesfunctionYesYes
        virDomainUpdateDeviceFlagsNofunction
        virEventAddHandleFuncYesdelegateY= esYes
        virEventAddTimeoutFuncYesdelegate= YesYes
        virEventHandleCallbackYesdelegate= YesvirEventRegisterImplYesYesYes
        virEventRegisterImplYesfunctionYe= svirEventRegisterImplYesYesYes= Yes
        virEventRemoveHandleFuncYesdelegateYes
        virEventRemoveTimeoutFuncYesdelegateYes
        virEventTimeoutCallbackYesdelegatevirEventRegisterImplYesYesYes
        virEventUpdateHandleFuncYesdelegateYes
        virEventUpdateTimeoutFuncYesdelegateYes
        virFreeCallbackYesfunctionYesvirEventRegisterImplYesYesYesYes
        virGetVersionYesfunctionYesYes
        virInitializeYesfunctionYesYes
        virInterfaceCreateNofunction
        virInterfaceDefineXMLNofunction
        virInterfaceDestroyNofunction
        virInterfaceFreeNofunction
        virInterfaceGetConnectNofunction<= /td>
        virInterfaceGetMACStringNofunction
        virInterfaceGetNameNofunction
        virInterfaceGetXMLDescNofunction<= /td>
        virInterfaceIsActiveNofunction
        virInterfaceLookupByMACStringNofunction
        virInterfaceLookupByNameNofunction
        virInterfaceRef Nofunction
        virInterfaceUndefineNofunction
        virNWFilterDefineXMLNofunction
        virNWFilterFreeNofunction
        virNWFilterGetNameNofunction
        virNWFilterGetUUIDNofunction
        virNWFilterGetUUIDStringNofunction
        virNWFilterGetXMLDescNofunction
        virNWFilterLookupByName Nofunction
        virNWFilterLookupByUUIDNofunction=
        virNWFilterLookupByUUIDStringNofunction
        virNWFilterRef Nofunction
        virNWFilterUndefineNofunction
        virNetworkCreateYesfunctionYesYes
        virNetworkCreateXMLYesfunctionNo<= /td>Maybe
        virNetworkDefineXMLYesfunctionYes= Yes
        virNetworkDestroyYesfunctionYesYes
        virNetworkFreeYesfunctionYesYes
        virNetworkGetAutostartYesfunction= NoMaybe
        virNetworkGetBridgeNameYesfunctionMaybe
        virNetworkGetConnectYesfunctionNo= Maybe
        virNetworkGetNameYesfunctionNoMaybe
        virNetworkGetUUIDNofunction
        virNetworkGetUUIDString YesfunctionYes
        virNetworkGetXMLDescYesfunctionYe= sYes
        virNetworkIsActiveYesfunctionYes<= /td>Yes
        virNetworkIsPersistentYesfunction= YesYes
        virNetworkLookupByNameYesfunction= YesYes
        virNetworkLookupByUUIDYesfunction= NoMaybe
        virNetworkLookupByUUIDStringYesfunctionNoMaybe
        virNetworkRefYesfunctionNoMaybe
        virNetworkSetAutostartYesfunction= YesYes
        virNetworkUndefineYesfunctionYes<= /td>Yes
        virNodeDeviceCreateXMLNofunction<= /td>
        virNodeDeviceDestroyNofunction
        virNodeDeviceDettachNofunction
        virNodeDeviceFreeNofunction
        virNodeDeviceGetNameNofunction
        virNodeDeviceGetParentNofunction<= /td>
        virNodeDeviceGetXMLDescYesfunctionYes
        virNodeDeviceListCapsNofunction
        virNodeDeviceLookupByNameYesfunctionYes
        virNodeDeviceNumOfCapsNofunction<= /td>
        virNodeDeviceReAttachNofunction
        virNodeDeviceRefNofunction
        virNodeDeviceResetNofunction
        virNodeGetCellsFreeMemoryNofunction
        virNodeGetFreeMemoryYesfunctionNo= Maybe
        virNodeGetInfoYesfunctionNoMaybe
        virNodeGetSecurityModel Nofunction
        virNodeListDevicesYesfunctionYes<= /td>Yes
        virNodeNumOfDevicesYesfunctionYes= Yes
        virSecretDefineXMLNofunction
        virSecretFree Nofunction
        virSecretGetConnectNofunction
        virSecretGetUUIDNofunction
        virSecretGetUUIDString Nofunction
        virSecretGetUsageIDNofunction
        virSecretGetUsageTypeNofunction
        virSecretGetValueNofunction
        virSecretGetXMLDescNofunction
        virSecretLookupByUUIDNofunction
        virSecretLookupByUUIDStringNofunction
        virSecretLookupByUsageNofunction<= /td>
        virSecretRefNofunction
        virSecretSetValueNofunction
        virSecretUndefineNofunction
        virStoragePoolBuildYesfunctionNo<= /td>Maybe
        virStoragePoolCreateYesfunctionYe= sYes
        virStoragePoolCreateXML YesfunctionMaybe
        virStoragePoolDefineXMLYesfunctionYes
        virStoragePoolDeleteYesfunctionNo= Maybe
        virStoragePoolDestroyYesfunctionY= esYes
        virStoragePoolFreeYesfunctionYes<= /td>Yes
        virStoragePoolGetAutostartYesfunctionNoMaybe
        virStoragePoolGetConnectYesfunctionMaybe
        virStoragePoolGetInfoYesfunctionY= esYes
        virStoragePoolGetNameYesfunctionY= esYes
        virStoragePoolGetUUIDYesfunctionN= oMaybe
        virStoragePoolGetUUIDStringYesfunctionYesYes
        virStoragePoolGetXMLDescYesfunctionYes
        virStoragePoolIsActiveYesfunction= YesYes
        virStoragePoolIsPersistentYesfunctionYesYes
        virStoragePoolListVolumesYesfunctionYes
        virStoragePoolLookupByNameYesfunctionYesYes
        virStoragePoolLookupByUUIDYesfunctionNoMaybe
        virStoragePoolLookupByUUIDStringYesfunctio= nNoMaybe
        virStoragePoolLookupByVolumeYesfunctionNoMaybe
        virStoragePoolNumOfVolumesYesfunctionYesYes
        virStoragePoolRefYesfunctionNoMaybe
        virStoragePoolRefreshYesfunctionN= oMaybe
        virStoragePoolSetAutostartYesfunctionYesYes
        virStoragePoolUndefineYesfunction= YesYes
        virStorageVolCreateXMLYesfunction= YesYes
        virStorageVolCreateXMLFromYesfunctionNoMaybe
        virStorageVolDeleteYesfunctionYes= Yes
        virStorageVolFreeYesfunctionNoMaybe
        virStorageVolGetConnect YesfunctionMaybe
        virStorageVolGetInfoYesfunctionYe= sYes
        virStorageVolGetKeyYesfunctionYes= Yes
        virStorageVolGetNameYesfunctionYe= sYes
        virStorageVolGetPathYesfunctionYe= sYes
        virStorageVolGetXMLDesc YesfunctionYes
        virStorageVolLookupByKeyYesfunctionYes
        virStorageVolLookupByNameYesfunctionYes
        virStorageVolLookupByPathYesfunctionYes
        virStorageVolRefYesfunctionNoNo
        virStorageVolWipeNofunction
        virStreamAbort Nofunction
        virStreamEventAddCallbackNofunction
        virStreamEventCallbackNodelegate<= /td>
        virStreamEventRemoveCallbackNofunction
        virStreamEventUpdateCallbackNofunction
        virStreamFinish Nofunction
        virStreamFree Nofunction
        virStreamNewNofunction
        virStreamRecvNofunction<= /td>
        virStreamRecvAllNofunction
        virStreamRefNofunction
        virStreamSendNofunction<= /td>
        virStreamSendAllNofunction
        virStreamSinkFuncNodelegate
        virStreamSourceFuncNodelegate
        virGetLastErrorYesfunctionYesvirConnectSetErrorFuncYesYesYesYes=
        virConnSetErrorFuncYesfunctionYes= virConnectSetErrorFuncYesYesYes
        virErrorFuncYesdelegateYesYesYesYe= sYes
        --=20 2.35.1 From nobody Fri May 10 15:26:10 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=1649084723; cv=none; d=zohomail.com; s=zohoarc; b=MfkdYtQE4+KdDkP0oANPS4pVJev8ut+v7MX04t0kXNNNP7HHyyWwP08xUWXbB8uV1qoJeSfXV3YoHQpxxgws+abTFnnMe8EsyKjYes257/HKsLfzuiYLZK3vUU+hOBqn84OTbG75qdhezWJrdX0aaWEYTb5wOFiy5bwMMy3pe7c= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649084723; 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=Z1RCTq1su3b6bk0HNshoHcMgOeVF5u978xxHCw0jybA=; b=Ij6yW2afDk3ZpbjffTO1SlcHtJ/bkIef1m2ThTVIJ0RdLreY/51YP13PBd+NgWGwvQShTS4rlaxh4rkQtUl8bJ5VhPuiHcRPfYExqW/t8zESw0rWN46y4iiXX6vYi5kyHCo9q/IjmLTeBCtuQL5MQjA2NSQKtQrvBdhBY9rUisA= 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 1649084723493415.56202591491456; Mon, 4 Apr 2022 08:05:23 -0700 (PDT) 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-323-Mb6uGIdIO0KFf0ILv1VyOw-1; Mon, 04 Apr 2022 11:04:41 -0400 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 9BE0180346E; Mon, 4 Apr 2022 15:04:35 +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 8751140CFD1C; Mon, 4 Apr 2022 15:04:35 +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 5E92119451F2; Mon, 4 Apr 2022 15:04:35 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B845C19451F2 for ; Mon, 4 Apr 2022 15:04:33 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 97ACF14582FB; Mon, 4 Apr 2022 15:04:33 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id EEB3514583CB for ; Mon, 4 Apr 2022 15:04:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649084722; 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=Z1RCTq1su3b6bk0HNshoHcMgOeVF5u978xxHCw0jybA=; b=gMb0xVvACXveGYBhr6S+rhuIUXMPCFo3zUVafzP6yXKMY5VQL0lfdjfifEIfeV4LTAM+Mp hBCaXwzn1dEuBeotYxCMic/kbtGpbpWOW+5Jg/ehWKxY9bIf0afg0zde+tU2Q1x1WgN8OE 88bz5DTvI/AUSqfRW8aMKUdNIuL0Jks= X-MC-Unique: Mb6uGIdIO0KFf0ILv1VyOw-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 7/7] docs: convert 'csharp' page to rst Date: Mon, 4 Apr 2022 17:04:24 +0200 Message-Id: <5b50cdff29c91321cc996fa27890e44f511d6b44.1649084492.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 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-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1649084724464100001 Signed-off-by: Peter Krempa Reviewed-by: Pavel Hrdina --- docs/csharp.html.in | 52 --------------------------------------------- docs/csharp.rst | 38 +++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 39 insertions(+), 53 deletions(-) delete mode 100644 docs/csharp.html.in create mode 100644 docs/csharp.rst diff --git a/docs/csharp.html.in b/docs/csharp.html.in deleted file mode 100644 index f94c08ff8d..0000000000 --- a/docs/csharp.html.in +++ /dev/null @@ -1,52 +0,0 @@ - - - - -

        C# API bindings

        - -
          - -

          Description

          - -

          - The C# libvirt bindings are a class library. They use a Microsoft - Visual Studio project architecture, and have been tested with Windows - .NET, and Mono, on both Linux and Windows. -

          -

          - Compiling them produces LibvirtBindings.dll, which can - be added as a .NET reference to any .NET project needing access - to libvirt. -

          - -

          Requirements

          - -

          - These bindings depend upon the libvirt libraries being installed. -

          -

          - In the .NET case, this is libvirt-0.dll, produced from - compiling libvirt for windows. -

          - -

          GIT source repository

          -

          - The C# bindings source code is maintained in a git repository available on - gitlab.com: -

          - -
          -git clone https://gitlab.com/libvirt/libvirt-csharp.git
-
          - -

          Authors

          - -

          - The C# bindings are the work of Arnaud Champion - <arnaud.champion= AT devatom.fr>, - based upon the previous work of Jarom=C3=ADr =C4=8Cervenka. -

          - - - diff --git a/docs/csharp.rst b/docs/csharp.rst new file mode 100644 index 0000000000..96fac1b442 --- /dev/null +++ b/docs/csharp.rst @@ -0,0 +1,38 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +C# API bindings +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Description +----------- + +The C# libvirt bindings are a class library. They use a Microsoft Visual S= tudio +project architecture, and have been tested with Windows .NET, and Mono, on= both +Linux and Windows. + +Compiling them produces **LibvirtBindings.dll**, which can be added as a .= NET +reference to any .NET project needing access to libvirt. + +Requirements +------------ + +These bindings depend upon the libvirt libraries being installed. + +In the .NET case, this is **libvirt-0.dll**, produced from compiling libvi= rt for +windows. + +GIT source repository +--------------------- + +The C# bindings source code is maintained in a ``git`` repository availabl= e on +`gitlab.com `__: + +:: + + git clone https://gitlab.com/libvirt/libvirt-csharp.git + +Authors +------- + +The C# bindings are the work of Arnaud Champion <`arnaud.champion AT +devatom.fr `__>, based upon the +previous work of Jarom=C3=ADr =C4=8Cervenka. diff --git a/docs/meson.build b/docs/meson.build index f54b56ed01..2295fbf752 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -19,7 +19,6 @@ docs_assets =3D [ docs_html_in_files =3D [ '404', - 'csharp', 'docs', 'formatcaps', 'formatdomaincaps', @@ -52,6 +51,7 @@ docs_rst_files =3D [ 'compiling', 'contact', 'contribute', + 'csharp', 'daemons', 'dbus', 'downloads', --=20 2.35.1