From nobody Sun May 5 18:42:52 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.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 63.128.21.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=1615549499; cv=none; d=zohomail.com; s=zohoarc; b=ZJJQApGhVi/3RteiKTi2NzKVQd86UXf0koPsQFloW1GRSJH1pWdYNk/YxlsT3sgm/A1cWcSzHIZ3AjGCjQwWmZroOiR6DJ8OPttdgGumEVM5BgjtmQ1k9YXctkLodN9dy3pojtfqsrwWUTH5LMasnM6jU09dvJQwWAi5w+hOgO0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549499; h=Content-Type:Content-Transfer-Encoding:Cc: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=R3nUDh6pCcTQE6ZeooTue1UTwGZgCZiiExptmrv1B1c=; b=UNiIP76iXpuaDg6L0WOtjZSQHe8kudttwxMh/effBT0+SH6zwonhnlh9acSvqT93BrDQTfr5NEuWGFY8kWriWJ+W8NLNUDZ/HBOj2K74I6NXB8zYEco9bQ9Y1qiIZfsGtLBDr+NmuUZdDjZq6/jCAG50t7S6r8Rb1QAeRRRkzyk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1615549499531995.4630425759875; Fri, 12 Mar 2021 03:44:59 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-256-U85ypWCONxOHXVsWOxJ-oQ-1; Fri, 12 Mar 2021 06:44:56 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A52F01966321; Fri, 12 Mar 2021 11:44:50 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 7E3135C1D1; Fri, 12 Mar 2021 11:44:49 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 216731800232; Fri, 12 Mar 2021 11:44:49 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhHLO024833 for ; Fri, 12 Mar 2021 06:43:17 -0500 Received: by smtp.corp.redhat.com (Postfix) id D4A9360657; Fri, 12 Mar 2021 11:43:17 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 04CA060636; Fri, 12 Mar 2021 11:43:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549498; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=R3nUDh6pCcTQE6ZeooTue1UTwGZgCZiiExptmrv1B1c=; b=KuCLi3bK/8TygJ73x9LfUNbjUgBiLOoNKC9xSR+04ZkAh1R587XovZLYdG0ZYX8QJvMbeN ZZHr+yRyWlFtS/8sBDXHEZWTisQ30Bv8imiRwUj2ZRjGZhQ/rt4BKO+6liJZnm+EwJJ75r Gv3V5S/sh5a/3UlJfsORcZKkCjl/URk= X-MC-Unique: U85ypWCONxOHXVsWOxJ-oQ-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 1/9] docs: html.in: Convert aclpolkit to rst Date: Fri, 12 Mar 2021 12:43:04 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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) Content-Type: text/plain; charset="utf-8" Signed-off-by: Erik Skultety Reviewed-by: Peter Krempa --- docs/aclpolkit.html.in | 523 ----------------------------------------- docs/aclpolkit.rst | 310 ++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 311 insertions(+), 524 deletions(-) delete mode 100644 docs/aclpolkit.html.in create mode 100644 docs/aclpolkit.rst diff --git a/docs/aclpolkit.html.in b/docs/aclpolkit.html.in deleted file mode 100644 index a82001187e..0000000000 --- a/docs/aclpolkit.html.in +++ /dev/null @@ -1,523 +0,0 @@ - - - - -

Polkit access control

- -

- Libvirt's client access control framework a= llows - administrators to setup fine grained permission rules across client = users, - managed objects and API operations. This allows client connections - to be locked down to a minimal set of privileges. The polkit driver - provides a simple implementation of the access control framework. -

- -
    - -

    Introduction

    - -

    - A default install of libvirt will typically use - polkit= - to authenticate the initial user connection to libvirtd. This is a - very coarse grained check though, either allowing full read-write - access to all APIs, or just read-only access. The polkit access - control driver in libvirt builds on this capability to allow for - fine grained control over the operations a user may perform on an - object. -

    - -

    Permission names

    - -

    - The libvirt object names and permission n= ames - are mapped onto polkit action names using the simple pattern: -

    - - 
    org.libvirt.api.$object.$permission
-
    - -

    - The only caveat is that any underscore characters in the - object or permission names are converted to hyphens. So, - for example, the search_storage_vols permission - on the storage_pool object maps to the polkit - action: -

    - 
    org.libvirt.api.storage-pool.search-storage-vols
-
    - -

    - The default policy for any permission which corresponds to - a "read only" operation, is to allow access. All other - permissions default to deny access. -

    - -

    Object identity attributes

    - -

    - To allow polkit authorization rules to be written to match - against individual object instances, libvirt provides a number - of authorization detail attributes when performing a permission - check. The set of attributes varies according to the type - of object being checked -

    - -

    virConnectPtr

    - - - - - - - - - - - - - -
    AttributeDescription
    connect_driverName of the libvirt connection driver
    - -

    virDomainPtr

    - - - - - - - - - - - - - - - - - - - - - -
    AttributeDescription
    connect_driverName of the libvirt connection driver
    domain_nameName of the domain, unique to the local host
    domain_uuidUUID of the domain, globally unique
    - -

    virInterfacePtr

    - - - - - - - - - - - - - - - - - - - - - -
    AttributeDescription
    connect_driverName of the libvirt connection driver
    interface_nameName of the network interface, unique to the local host
    interface_macaddrMAC address of the network interface, not unique
    - -

    virNetworkPtr

    - - - - - - - - - - - - - - - - - - - - - -
    AttributeDescription
    connect_driverName of the libvirt connection driver
    network_nameName of the network, unique to the local host
    network_uuidUUID of the network, globally unique
    - -

    virNodeDevicePtr

    - - - - - - - - - - - - - - - - - -
    AttributeDescription
    connect_driverName of the libvirt connection driver
    node_device_nameName of the node device, unique to the local host
    - -

    virNWFilterPtr

    - - - - - - - - - - - - - - - - - - - - - -
    AttributeDescription
    connect_driverName of the libvirt connection driver
    nwfilter_nameName of the network filter, unique to the local host
    nwfilter_uuidUUID of the network filter, globally unique
    - -

    virSecretPtr

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    AttributeDescription
    connect_driverName of the libvirt connection driver
    secret_uuidUUID of the secret, globally unique
    secret_usage_volumeName of the associated volume, if any
    secret_usage_cephName of the associated Ceph server, if any
    secret_usage_targetName of the associated iSCSI target, if any
    secret_usage_nameName of the associated TLS secret, if any
    - -

    virStoragePoolPtr

    - - - - - - - - - - - - - - - - - - - - - -
    AttributeDescription
    connect_driverName of the libvirt connection driver
    pool_nameName of the storage pool, unique to the local host
    pool_uuidUUID of the storage pool, globally unique
    - -

    virStorageVolPtr

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    AttributeDescription
    connect_driverName of the libvirt connection driver
    pool_nameName of the storage pool, unique to the local host
    pool_uuidUUID of the storage pool, globally unique
    vol_nameName of the storage volume, unique to the pool
    vol_keyKey of the storage volume, globally unique
    - -

    Hypervisor Driver connect_driver

    -

    - The connect_driver parameter describes the - client's remote Connection Driver - name based on the URI used for the - connection. -

    -

    - Since 4.1.0, when calling an API - outside the scope of the primary connection driver, the - primary driver will attempt to open a secondary connection - to the specific API driver in order to process the API. For - example, when hypervisor domain processing needs to make an - API call within the storage driver or the network filter driver - an attempt to open a connection to the "storage" or "nwfilter" - driver will be made. Similarly, a "storage" primary connection - may need to create a connection to the "secret" driver in order - to process secrets for the API. If successful, then calls to - those API's will occur in the connect_driver context - of the secondary connection driver rather than in the context of - the primary driver. This affects the connect_driver - returned from rule generation from the action.loookup - function. The following table provides a list of the various - connection drivers and the connect_driver name - used by each regardless of primary or secondary connection. - The access denied error message from libvirt will list the - connection driver by name that denied the access. -

    - -

    Connection Driver Name

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Connection Driverconnect_driver name
    bhyvebhyve
    esxESX
    hypervHyper-V
    interfaceinterface
    xenXen
    lxcLXC
    networknetwork
    nodedevnodedev
    nwfilterNWFilter
    openvzOPENVZ
    qemuQEMU
    secretsecret
    storagestorage
    vboxVBOX
    vmwareVMWARE
    vzvz
    - - -

    User identity attributes

    - -

    - At this point in time, the only attribute provided by - libvirt to identify the user invoking the operation - is the PID of the client program. This means that the - polkit access control driver is only useful if connections - to libvirt are restricted to its UNIX domain socket. If - connections are being made to a TCP socket, no identifying - information is available and access will be denied. - Also note that if the client is connecting via an SSH - tunnel, it is the local SSH user that will be identified. - In future versions, it is expected that more information - about the client user will be provided, including the - SASL / Kerberos username and/or x509 distinguished - name obtained from the authentication provider in use. -

    - - -

    Writing access control policies

    - -

    - If using versions of polkit prior to 0.106 then it is only - possible to validate (user, permission) pairs via the .pkla - files. Fully validation of the (user, permission, object) triple - requires the new JavaScript .rules support that - was introduced in version 0.106. The latter is what will be - described here. -

    - -

    - Libvirt does not ship any rules files by default. It merely - provides a definition of the default behaviour for each - action (permission). As noted earlier, permissions which - correspond to read-only operations in libvirt will be allowed - to all users by default; everything else is denied by default. - Defining custom rules requires creation of a file in the - /etc/polkit-1/rules.d directory with a name - chosen by the administrator (100-libvirt-acl.rules - would be a reasonable choice). See the polkit(8) - manual page for a description of how to write these files - in general. The key idea is to create a file containing - something like -

    - - 
    -polkit.addRule(function(action, subject) {
-  ....logic to check 'action' and 'subject'...
-});
-
    - -

    - In this code snippet above, the action object - instance will represent the libvirt permission being checked - along with identifying attributes for the object it is being - applied to. The subject meanwhile will identify - the libvirt client app (with the caveat above about it only - dealing with local clients connected via the UNIX socket). - On the action object, the permission name is - accessible via the id attribute, while the - object identifying attributes are exposed via the - lookup method. -

    - -

    - See - source code - for a more complex example. -

    - -

    Example: restricting ability to connect to dri= vers

    - -

    - Consider a local user berrange - who has been granted permission to connect to libvirt in - full read-write mode. The goal is to only allow them to - use the QEMU driver and not the Xen or LXC - drivers which are also available in libvirtd. - To achieve this we need to write a rule which checks - whether the connect_driver attribute - is QEMU, and match on an action - name of org.libvirt.api.connect.getattr. Using - the javascript rules format, this ends up written as -

    - - 
    -polkit.addRule(function(action, subject) {
-    if (action.id =3D=3D "org.libvirt.api.connect.getattr" &&
-        subject.user =3D=3D "berrange") {
-          if (action.lookup("connect_driver") =3D=3D 'QEMU') {
-            return polkit.Result.YES;
-          } else {
-            return polkit.Result.NO;
-          }
-    }
-});
-
    - -

    Example: restricting access to a single domain<= /a>

    - -

    - Consider a local user berrange - who has been granted permission to connect to libvirt in - full read-write mode. The goal is to only allow them to - see the domain called demo on the LXC driver. - To achieve this we need to write a rule which checks - whether the connect_driver attribute - is LXC and the domain_name - attribute is demo, and match on an action - name of org.libvirt.api.domain.getattr. Using - the javascript rules format, this ends up written as -

    - - 
    -polkit.addRule(function(action, subject) {
-    if (action.id =3D=3D "org.libvirt.api.domain.getattr" &&
-        subject.user =3D=3D "berrange") {
-          if (action.lookup("connect_driver") =3D=3D 'LXC' &&
-              action.lookup("domain_name") =3D=3D 'demo') {
-            return polkit.Result.YES;
-          } else {
-            return polkit.Result.NO;
-          }
-    }
-});
-
    - - diff --git a/docs/aclpolkit.rst b/docs/aclpolkit.rst new file mode 100644 index 0000000000..09e5d9ea27 --- /dev/null +++ b/docs/aclpolkit.rst @@ -0,0 +1,310 @@ +.. role:: since + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Polkit access control +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Libvirt's client `access control framework `__ allows +administrators to setup fine grained permission rules across client +users, managed objects and API operations. This allows client +connections to be locked down to a minimal set of privileges. The polkit +driver provides a simple implementation of the access control framework. + +.. contents:: + +Introduction +------------ + +A default install of libvirt will typically use +`polkit `__ to +authenticate the initial user connection to libvirtd. This is a very +coarse grained check though, either allowing full read-write access to +all APIs, or just read-only access. The polkit access control driver in +libvirt builds on this capability to allow for fine grained control over +the operations a user may perform on an object. + +Permission names +---------------- + +The libvirt `object names and permission names `__ are +mapped onto polkit action names using the simple pattern: + +:: + + org.libvirt.api.$object.$permission + +The only caveat is that any underscore characters in the object or +permission names are converted to hyphens. So, for example, the +``search_storage_vols`` permission on the ``storage_pool`` object maps +to the polkit action: + +:: + + org.libvirt.api.storage-pool.search-storage-vols + +The default policy for any permission which corresponds to a "read only" +operation, is to allow access. All other permissions default to deny +access. + +Object identity attributes +-------------------------- + +To allow polkit authorization rules to be written to match against +individual object instances, libvirt provides a number of authorization +detail attributes when performing a permission check. The set of +attributes varies according to the type of object being checked + +virConnectPtr +~~~~~~~~~~~~~ + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D +Attribute Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D +connect_driver Name of the libvirt connection driver +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + +virDomainPtr +~~~~~~~~~~~~ + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D +Attribute Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D +connect_driver Name of the libvirt connection driver +domain_name Name of the domain, unique to the local host +domain_uuid UUID of the domain, globally unique +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D + +virInterfacePtr +~~~~~~~~~~~~~~~ + ++-------------------+-----------------------------------------------------= ----+ +| Attribute | Description = | ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D+ +| connect_driver | Name of the libvirt connection driver = | ++-------------------+-----------------------------------------------------= ----+ +| interface_name | Name of the network interface, unique to the local h= ost | ++-------------------+-----------------------------------------------------= ----+ +| interface_macaddr | MAC address of the network interface, not unique = | ++-------------------+-----------------------------------------------------= ----+ + +virNetworkPtr +~~~~~~~~~~~~~ + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Attribute Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +connect_driver Name of the libvirt connection driver +network_name Name of the network, unique to the local host +network_uuid UUID of the network, globally unique +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +virNodeDevicePtr +~~~~~~~~~~~~~~~~ + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Attribute Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +connect_driver Name of the libvirt connection driver +node_device_name Name of the node device, unique to the local host +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +virNWFilterPtr +~~~~~~~~~~~~~~ + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Attribute Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +connect_driver Name of the libvirt connection driver +nwfilter_name Name of the network filter, unique to the local host +nwfilter_uuid UUID of the network filter, globally unique +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +virSecretPtr +~~~~~~~~~~~~ + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Attribute Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +connect_driver Name of the libvirt connection driver +secret_uuid UUID of the secret, globally unique +secret_usage_volume Name of the associated volume, if any +secret_usage_ceph Name of the associated Ceph server, if any +secret_usage_target Name of the associated iSCSI target, if any +secret_usage_name Name of the associated TLS secret, if any +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +virStoragePoolPtr +~~~~~~~~~~~~~~~~~ + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Attribute Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +connect_driver Name of the libvirt connection driver +pool_name Name of the storage pool, unique to the local host +pool_uuid UUID of the storage pool, globally unique +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +virStorageVolPtr +~~~~~~~~~~~~~~~~ + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Attribute Description +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +connect_driver Name of the libvirt connection driver +pool_name Name of the storage pool, unique to the local host +pool_uuid UUID of the storage pool, globally unique +vol_name Name of the storage volume, unique to the pool +vol_key Key of the storage volume, globally unique +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Hypervisor Driver connect_driver +-------------------------------- + +The ``connect_driver`` parameter describes the client's `remote +Connection Driver `__ name based on the `URI `__ +used for the connection. + +:since:`Since 4.1.0`, when calling an API outside the scope of the primary +connection driver, the primary driver will attempt to open a secondary +connection to the specific API driver in order to process the API. For +example, when hypervisor domain processing needs to make an API call +within the storage driver or the network filter driver an attempt to +open a connection to the "storage" or "nwfilter" driver will be made. +Similarly, a "storage" primary connection may need to create a +connection to the "secret" driver in order to process secrets for the +API. If successful, then calls to those API's will occur in the +``connect_driver`` context of the secondary connection driver rather +than in the context of the primary driver. This affects the +``connect_driver`` returned from rule generation from the +``action.loookup`` function. The following table provides a list of the +various connection drivers and the ``connect_driver`` name used by each +regardless of primary or secondary connection. The access denied error +message from libvirt will list the connection driver by name that denied +the access. + +Connection Driver Name +~~~~~~~~~~~~~~~~~~~~~~ + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Connection Driver ``connect_driver`` name +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +bhyve bhyve +esx ESX +hyperv Hyper-V +interface interface +xen Xen +lxc LXC +network network +nodedev nodedev +nwfilter NWFilter +openvz OPENVZ +qemu QEMU +secret secret +storage storage +vbox VBOX +vmware VMWARE +vz vz +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +User identity attributes +------------------------ + +At this point in time, the only attribute provided by libvirt to +identify the user invoking the operation is the PID of the client +program. This means that the polkit access control driver is only useful +if connections to libvirt are restricted to its UNIX domain socket. If +connections are being made to a TCP socket, no identifying information +is available and access will be denied. Also note that if the client is +connecting via an SSH tunnel, it is the local SSH user that will be +identified. In future versions, it is expected that more information +about the client user will be provided, including the SASL / Kerberos +username and/or x509 distinguished name obtained from the authentication +provider in use. + +Writing access control policies +------------------------------- + +If using versions of polkit prior to 0.106 then it is only possible to +validate (user, permission) pairs via the ``.pkla`` files. Fully +validation of the (user, permission, object) triple requires the new +JavaScript ``.rules`` support that was introduced in version 0.106. The +latter is what will be described here. + +Libvirt does not ship any rules files by default. It merely provides a +definition of the default behaviour for each action (permission). As +noted earlier, permissions which correspond to read-only operations in +libvirt will be allowed to all users by default; everything else is +denied by default. Defining custom rules requires creation of a file in +the ``/etc/polkit-1/rules.d`` directory with a name chosen by the +administrator (``100-libvirt-acl.rules`` would be a reasonable choice). +See the ``polkit(8)`` manual page for a description of how to write +these files in general. The key idea is to create a file containing +something like + +:: + + polkit.addRule(function(action, subject) { + ....logic to check 'action' and 'subject'... + }); + +In this code snippet above, the ``action`` object instance will +represent the libvirt permission being checked along with identifying +attributes for the object it is being applied to. The ``subject`` +meanwhile will identify the libvirt client app (with the caveat above +about it only dealing with local clients connected via the UNIX socket). +On the ``action`` object, the permission name is accessible via the +``id`` attribute, while the object identifying attributes are exposed +via the ``lookup`` method. + +See `source +code `__ +for a more complex example. + +Example: restricting ability to connect to drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Consider a local user ``berrange`` who has been granted permission to +connect to libvirt in full read-write mode. The goal is to only allow +them to use the ``QEMU`` driver and not the Xen or LXC drivers which are +also available in libvirtd. To achieve this we need to write a rule +which checks whether the ``connect_driver`` attribute is ``QEMU``, and +match on an action name of ``org.libvirt.api.connect.getattr``. Using +the javascript rules format, this ends up written as + +:: + + polkit.addRule(function(action, subject) { + if (action.id =3D=3D "org.libvirt.api.connect.getattr" && + subject.user =3D=3D "berrange") { + if (action.lookup("connect_driver") =3D=3D 'QEMU') { + return polkit.Result.YES; + } else { + return polkit.Result.NO; + } + } + }); + +Example: restricting access to a single domain +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Consider a local user ``berrange`` who has been granted permission to +connect to libvirt in full read-write mode. The goal is to only allow +them to see the domain called ``demo`` on the LXC driver. To achieve +this we need to write a rule which checks whether the ``connect_driver`` +attribute is ``LXC`` and the ``domain_name`` attribute is ``demo``, and +match on an action name of ``org.libvirt.api.domain.getattr``. Using the +javascript rules format, this ends up written as + +:: + + polkit.addRule(function(action, subject) { + if (action.id =3D=3D "org.libvirt.api.domain.getattr" && + subject.user =3D=3D "berrange") { + if (action.lookup("connect_driver") =3D=3D 'LXC' && + action.lookup("domain_name") =3D=3D 'demo') { + return polkit.Result.YES; + } else { + return polkit.Result.NO; + } + } + }); diff --git a/docs/meson.build b/docs/meson.build index 5536005125..0f402bbf6a 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'aclpolkit', 'api_extension', 'api', 'apps', @@ -106,6 +105,7 @@ docs_html_in_files =3D [ ] =20 docs_rst_files =3D [ + 'aclpolkit', 'advanced-tests', 'best-practices', 'ci', --=20 2.29.2 From nobody Sun May 5 18:42:52 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.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 216.205.24.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=1615549481; cv=none; d=zohomail.com; s=zohoarc; b=mtnikY7bUuwAFeynF8lkUMypTVESt8aXdvtK0smgI1vZu2WWfD1rXkLQ9KCOTHONJMasI+eXJh4AbKXghayZNMSQ5WUh4dhPjjKoM9zzYjR4/D2tiuLlG+OvCQxNCwrHJMLC/Mgq4BHxCZsJ3WoThPaBd0e3+Z1n8cJFlJmWq6o= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549481; h=Content-Type:Content-Transfer-Encoding:Cc: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=4qgj4n5vqVHZ3QeXi+G0JblQSpRQHrLylctHkl/VbgY=; b=Pmt0MvKO5PDWeCPj9RSW5/d5V9b+yg5TbOHA2JOvJ4WeOlUkpHoJolAatsm4QQuB0VJrjvbknVY2A5sFkNZIVAQXCe9aJnj267suBBqECZe//hm9KkVSAqfEDMRqIz0lkfIdh98PQh2Ty0kxXbAvhPnhzE9yYVMArUUlh+YwbdQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 161554948124737.98167288498553; Fri, 12 Mar 2021 03:44:41 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-317-zQ7VVtdBP4iwembI7BcklA-1; Fri, 12 Mar 2021 06:44:37 -0500 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 6DEF48030A0; Fri, 12 Mar 2021 11:44:30 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 24BC610016FC; Fri, 12 Mar 2021 11:44:28 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 12B1957DC0; Fri, 12 Mar 2021 11:44:22 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhJEC024844 for ; Fri, 12 Mar 2021 06:43:19 -0500 Received: by smtp.corp.redhat.com (Postfix) id 0EEBC60657; Fri, 12 Mar 2021 11:43:19 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3440460636; Fri, 12 Mar 2021 11:43:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549480; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=4qgj4n5vqVHZ3QeXi+G0JblQSpRQHrLylctHkl/VbgY=; b=GkvZFX6nlnTA3FQYBjIWOPOp180nnjaw60IUuA6/m0vADQva5TSL/H/E2ZlmKlUa5Ilyh4 tKvTDmS9lkxxLMpMDYXn3/0YYQKrreXU2CwP6HPZoG3lWJyLJmVEvxrpA9wpy8DsmLnaYx ryfjmV8hQ74oGf4EaCie0XzRqLOx3dg= X-MC-Unique: zQ7VVtdBP4iwembI7BcklA-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 2/9] docs: html.in: Convert api_extension to rst Date: Fri, 12 Mar 2021 12:43:05 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 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) Content-Type: text/plain; charset="utf-8" Signed-off-by: Erik Skultety Reviewed-by: Peter Krempa --- docs/api_extension.html.in | 376 ------------------------------------- docs/api_extension.rst | 291 ++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 292 insertions(+), 377 deletions(-) delete mode 100644 docs/api_extension.html.in create mode 100644 docs/api_extension.rst diff --git a/docs/api_extension.html.in b/docs/api_extension.html.in deleted file mode 100644 index e44c1c37b0..0000000000 --- a/docs/api_extension.html.in +++ /dev/null @@ -1,376 +0,0 @@ - - - - -

    Implementing a new API in Libvirt

    - -
      - -

      - This document walks you through the process of implementing a new - API in libvirt. Remember that new API consists of any new public - functions, as well as the addition of flags or extensions of XML use= d by - existing functions. -

      - -

      - Before you begin coding, it is critical that you propose your - changes on the libvirt mailing list and get feedback on your ideas to - make sure what you're proposing fits with the general direction of t= he - project. Even before doing a proof of concept implementation, send = an - email giving an overview of the functionality you think should be - added to libvirt. Someone may already be working on the feature you - want. Also, recognize that everything you write is likely to undergo - significant rework as you discuss it with the other developers, so - don't wait too long before getting feedback. -

      - -

      - Adding a new API to libvirt is not difficult, but there are quite a - few steps. This document assumes that you are familiar with C - programming and have checked out the libvirt code from the source co= de - repository and successfully built the existing tree. Instructions on - how to check out and build the code can be found at: -

      - -

      - https://libvirt.org/d= ownloads.html -

      - -

      - Once you have a working development environment, the steps to create= a - new API are: -

      -
        -
      1. define the public API
        2. -
      2. define the internal driver API
        3. -
      3. implement the public API
        4. -
      4. implement the remote protocol: -
          -
        1. define the wire protocol format
          2. -
        2. implement the RPC client
          3. -
        3. implement the server side dispatcher
          4. -
        -
        5. -
      5. use new API where appropriate in drivers
        6. -
      6. add virsh support
        7. -
      7. add common handling for new API
        8. -
      8. for each driver that can support the new API: -
          -
        1. add prerequisite support
          2. -
        2. fully implement new API
          3. -
        -
        9. -
      - -

      - It is, of course, possible to implement the pieces in any order, but - if the development tasks are completed in the order listed, the code - will compile after each step. Given the number of changes required, - verification after each step is highly recommended. -

      - -

      - Submit new code in the form of one patch per step. That's not to say - submit patches before you have working functionality--get the whole = thing - working and make sure you're happy with it. Then use git to break t= he - changes into pieces so you don't drop a big blob of code on the - mailing list in one go. Also, you should follow the upstream tree, = and - rebase your series to adapt your patches to work with any other chan= ges - that were accepted upstream during your development. -

      - -

      - Don't mix anything else into the patches you submit. The patches - should be the minimal changes required to implement the functionality - you're adding. If you notice a bug in unrelated code (i.e., code you - don't have to touch to implement your API change) during development, - create a patch that just addresses that bug and submit it - separately. -

      - -

      Defining the public API

      - -

      The first task is to define the public API. If the new API - involves an XML extension, you have to enhance the RelaxNG - schema and document the new elements or attributes:

      - -

      - docs/schemas/domaincommon.rng
      - docs/formatdomain.html.in -

      - -

      If the API extension involves a new function, you have to add a - declaration in the public header, and arrange to export the - function name (symbol) so other programs can link against the - libvirt library and call the new function:

      - -

      - include/libvirt/libvirt-$MODULE.h.in - src/libvirt_public.syms -

      - -

      - Please consult our - codin= g style - guide on elements and attribute names. -

      - -

      - This task is in many ways the most important to get right, since once - the API has been committed to the repository, it's libvirt's policy - never to change it. Mistakes in the implementation are bugs that you - can fix. Make a mistake in the API definition and you're stuck with - it, so think carefully about the interface and don't be afraid to - rework it as you go through the process of implementing it. -

      - -

      Defining the internal API

      - -

      - Each public API call is associated with a driver, such as a host - virtualization driver, a network virtualization driver, a storage - virtualization driver, a state driver, or a device monitor. Adding - the internal API is ordinarily a matter of adding a new member to the - struct representing one of these drivers. -

      - -

      - Of course, it's possible that the new API will involve the creation = of - an entirely new driver type, in which case the changes will include = the - creation of a new struct type to represent the new driver type. -

      - -

      The driver structs are defined in:

      - -

      src/driver-$MODULE.h

      - -

      - To define the internal API, first typedef the driver function - prototype and then add a new field for it to the relevant driver - struct. Then, update all existing instances of the driver to - provide a NULL stub for the new function. -

      - -

      Implementing the public API

      - -

      - Implementing the public API is largely a formality in which we wire = up - public API to the internal driver API. The public API implementation - takes care of some basic validity checks before passing control to t= he - driver implementation. In RFC 2119 vocabulary, this function: -

      - -
        -
      1. SHOULD log a message with VIR_DEBUG() indicating that it is - being called and its parameters;
        2. -
      2. MUST call virResetLastError();
        3. -
      3. SHOULD confirm that the connection is valid with - virCheckConnectReturn() or virCheckConnectGoto();
        4. -
      4. SECURITY: If the API requires a connection with write - privileges, MUST confirm that the connection flags do not - indicate that the connection is read-only with - virCheckReadOnlyGoto();
        5. -
      5. SHOULD do basic validation of the parameters that are being - passed in, using helpers like virCheckNonNullArgGoto();
        6. -
      6. MUST confirm that the driver for this connection exists and that - it implements this function;
        7. -
      7. MUST call the internal API;
        8. -
      8. SHOULD log a message with VIR_DEBUG() indicating that it is - returning, its return value, and status.
        9. -
      9. MUST return status to the caller.
        10. -
      - -

      The public API calls are implemented in:

      - -

      src/libvirt-$MODULE.c

      - -

      Implementing the remote protocol

      - -

      - Implementing the remote protocol is essentially a - straightforward exercise which is probably most easily - understood by referring to the existing code. -

      - -

      Defining the wire protocol format

      - -

      - Defining the wire protocol involves making additions to: -

      - -

      src/remote/remote_protocol.x

      - -

      - First, create two new structs for each new function that you're addi= ng - to the API. One struct describes the parameters to be passed to the - remote function, and a second struct describes the value returned by - the remote function. The one exception to this rule is that functio= ns - that return only 0 or -1 for status do not require a struct for retu= rned - data. -

      - -

      - Second, add values to the remote_procedure enum for each new function - added to the API. -

      - -

      - Once these changes are in place, it's necessary to run 'make rpcgen' - in the src directory to create the .c and .h files required by the - remote protocol code. This must be done on a Linux host using the - GLibC rpcgen program. Other rpcgen versions may generate code which - results in bogus compile time warnings. This regenerates the - following files: -

      - -

      - src/remote/remote_daemon_dispatch_stubs.h - src/remote/remote_daemon_dispatch.h - src/remote/remote_daemon_dispatch.c - src/remote/remote_protocol.c - src/remote/remote_protocol.h -

      - -

      Implement the RPC client

      - -

      - Implementing the RPC client uses the rpcgen generated .h files. - The remote method calls go in: -

      - -

      src/remote/remote_driver.c

      - -

      Each remote method invocation does the following:

      - -
        -
      1. locks the remote driver;
        2. -
      2. sets up the method arguments;
        3. -
      3. invokes the remote function;
        4. -
      4. checks the return value, if necessary;
        5. -
      5. extracts any returned data;
        6. -
      6. frees any returned data;
        7. -
      7. unlocks the remote driver.
        8. -
      - -

      Implement the server side dispatcher<= /h3> - -

      - Implementing the server side of the remote function call is simply a - matter of deserializing the parameters passed in from the remote - caller and passing them to the corresponding internal API function. - The server side dispatchers are implemented in: -

      - -

      src/remote/remote_daemon_dispatch.c

      - -

      Again, this step uses the .h files generated by make rpcgen.

      - -

      - After all three pieces of the remote protocol are complete, and - the generated files have been updated, it will be necessary to - update the file:

      - -

      src/remote_protocol-structs

      - -

      - This file should only have new lines added; modifications to - existing lines probably imply a backwards-incompatible API change. -

      - -

      Use the new API internally

      - -

      - Sometimes, a new API serves as a superset of existing API, by - adding more granularity in what can be managed. When this is - the case, it makes sense to share a common implementation by - making the older API become a trivial wrapper around the new - API, rather than duplicating the common code. This step should - not introduce any semantic differences for the old API, and is - not necessary if the new API has no relation to existing API. -

      - -

      Expose the new API in virsh

      - -

      - All new API should be manageable from the virsh command line - shell. This proves that the API is sufficient for the intended - purpose, and helps to identify whether the proposed API needs - slight changes for easier usage. However, remember that virsh - is used to connect to hosts running older versions of libvirtd, - so new commands should have fallbacks to an older API if - possible; implementing the virsh hooks at this point makes it - very easy to test these fallbacks. Also remember to document - virsh additions. -

      - -

      - A virsh command is composed of a few pieces of code. You need to - define an array of vshCmdInfo structs for each new command that - contain the help text and the command description text. You also ne= ed - an array of vshCmdOptDef structs to describe the command options. - Once you have those pieces in place you can write the function - implementing the virsh command. Finally, you need to add the new - command to the commands[] array. The following files need changes: -

      - -

      - tools/virsh-$MODULE.c
      - tools/virsh.pod -

      - -

      Implement the driver methods

      - -

      - So, after all that, we get to the fun part. All functionality in - libvirt is implemented inside a driver. Thus, here is where you - implement whatever functionality you're adding to libvirt. You'll - either need to add additional files to the src directory or extend - files that are already there, depending on what functionality you're - adding. -

      - -

      Implement common handling

      - -

      - If the new API is applicable to more than one driver, it may - make sense to provide some utility routines, or to factor some - of the work into the dispatcher, to avoid reimplementing the - same code in every driver. In the example code, this involved - adding a member to the virDomainDefPtr struct for mapping - between the XML API addition and the in-memory representation of - a domain, along with updating all clients to use the new member. - Up to this point, there have been no changes to existing - semantics, and the new APIs will fail unless they are used in - the same way as the older API wrappers. -

      - -

      Implement driver handling

      - -

      - The remaining patches should only touch one driver at a time. - It is possible to implement all changes for a driver in one - patch, but for review purposes it may still make sense to break - things into simpler steps. Here is where the new APIs finally - start working. -

      - -

      - It is always a good idea to patch the test driver in addition to the - target driver, to prove that the API can be used for more than one - driver. -

      - -

      - Any cleanups resulting from the changes should be added as separate - patches at the end of the series. -

      - -

      - Once you have working functionality, run ninja test on each patch - of the series before submitting patches. It may also be worth - writing tests for the libvirt-TCK testsuite to exercise your new API, - although those patches are not kept in the libvirt repository. -

      - - diff --git a/docs/api_extension.rst b/docs/api_extension.rst new file mode 100644 index 0000000000..02b39efd82 --- /dev/null +++ b/docs/api_extension.rst @@ -0,0 +1,291 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D +Implementing a new API in Libvirt +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +This document walks you through the process of implementing a new API in +libvirt. Remember that new API consists of any new public functions, as +well as the addition of flags or extensions of XML used by existing +functions. + +Before you begin coding, it is critical that you propose your changes on +the libvirt mailing list and get feedback on your ideas to make sure +what you're proposing fits with the general direction of the project. +Even before doing a proof of concept implementation, send an email +giving an overview of the functionality you think should be added to +libvirt. Someone may already be working on the feature you want. Also, +recognize that everything you write is likely to undergo significant +rework as you discuss it with the other developers, so don't wait too +long before getting feedback. + +Adding a new API to libvirt is not difficult, but there are quite a few +steps. This document assumes that you are familiar with C programming +and have checked out the libvirt code from the source code repository +and successfully built the existing tree. Instructions on how to check +out and build the code can be found at: + +https://libvirt.org/downloads.html + +Once you have a working development environment, the steps to create a +new API are: + +#. define the public API +#. define the internal driver API +#. implement the public API +#. implement the remote protocol: + + #. define the wire protocol format + #. implement the RPC client + #. implement the server side dispatcher + +#. use new API where appropriate in drivers +#. add virsh support +#. add common handling for new API +#. for each driver that can support the new API: + + #. add prerequisite support + #. fully implement new API + +It is, of course, possible to implement the pieces in any order, but if +the development tasks are completed in the order listed, the code will +compile after each step. Given the number of changes required, +verification after each step is highly recommended. + +Submit new code in the form of one patch per step. That's not to say +submit patches before you have working functionality--get the whole +thing working and make sure you're happy with it. Then use git to break +the changes into pieces so you don't drop a big blob of code on the +mailing list in one go. Also, you should follow the upstream tree, and +rebase your series to adapt your patches to work with any other changes +that were accepted upstream during your development. + +Don't mix anything else into the patches you submit. The patches should +be the minimal changes required to implement the functionality you're +adding. If you notice a bug in unrelated code (i.e., code you don't have +to touch to implement your API change) during development, create a +patch that just addresses that bug and submit it separately. + +Defining the public API +----------------------- + +The first task is to define the public API. If the new API involves an +XML extension, you have to enhance the RelaxNG schema and document the +new elements or attributes: + +``docs/schemas/domaincommon.rng docs/formatdomain.html.in`` + +If the API extension involves a new function, you have to add a +declaration in the public header, and arrange to export the function +name (symbol) so other programs can link against the libvirt library and +call the new function: + +``include/libvirt/libvirt-$MODULE.h.in src/libvirt_public.syms`` + +Please consult our `coding +style `__ guide on +elements and attribute names. + +This task is in many ways the most important to get right, since once +the API has been committed to the repository, it's libvirt's policy +never to change it. Mistakes in the implementation are bugs that you can +fix. Make a mistake in the API definition and you're stuck with it, so +think carefully about the interface and don't be afraid to rework it as +you go through the process of implementing it. + +Defining the internal API +------------------------- + +Each public API call is associated with a driver, such as a host +virtualization driver, a network virtualization driver, a storage +virtualization driver, a state driver, or a device monitor. Adding the +internal API is ordinarily a matter of adding a new member to the struct +representing one of these drivers. + +Of course, it's possible that the new API will involve the creation of +an entirely new driver type, in which case the changes will include the +creation of a new struct type to represent the new driver type. + +The driver structs are defined in: + +``src/driver-$MODULE.h`` + +To define the internal API, first typedef the driver function prototype +and then add a new field for it to the relevant driver struct. Then, +update all existing instances of the driver to provide a ``NULL`` stub +for the new function. + +Implementing the public API +--------------------------- + +Implementing the public API is largely a formality in which we wire up +public API to the internal driver API. The public API implementation +takes care of some basic validity checks before passing control to the +driver implementation. In RFC 2119 vocabulary, this function: + +#. SHOULD log a message with VIR_DEBUG() indicating that it is being + called and its parameters; +#. MUST call virResetLastError(); +#. SHOULD confirm that the connection is valid with + virCheckConnectReturn() or virCheckConnectGoto(); +#. **SECURITY: If the API requires a connection with write privileges, + MUST confirm that the connection flags do not indicate that the + connection is read-only with virCheckReadOnlyGoto();** +#. SHOULD do basic validation of the parameters that are being passed + in, using helpers like virCheckNonNullArgGoto(); +#. MUST confirm that the driver for this connection exists and that it + implements this function; +#. MUST call the internal API; +#. SHOULD log a message with VIR_DEBUG() indicating that it is + returning, its return value, and status. +#. MUST return status to the caller. + +The public API calls are implemented in: + +``src/libvirt-$MODULE.c`` + +Implementing the remote protocol +-------------------------------- + +Implementing the remote protocol is essentially a straightforward +exercise which is probably most easily understood by referring to the +existing code. + +Defining the wire protocol format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Defining the wire protocol involves making additions to: + +``src/remote/remote_protocol.x`` + +First, create two new structs for each new function that you're adding +to the API. One struct describes the parameters to be passed to the +remote function, and a second struct describes the value returned by the +remote function. The one exception to this rule is that functions that +return only 0 or -1 for status do not require a struct for returned +data. + +Second, add values to the remote_procedure enum for each new function +added to the API. + +Once these changes are in place, it's necessary to run 'make rpcgen' in +the src directory to create the .c and .h files required by the remote +protocol code. This must be done on a Linux host using the GLibC rpcgen +program. Other rpcgen versions may generate code which results in bogus +compile time warnings. This regenerates the following files: + +``src/remote/remote_daemon_dispatch_stubs.h src/remote/remote_daem= on_dispatch.h src/remote/remote_daemon_dispatch.c src/remot= e/remote_protocol.c src/remote/remote_protocol.h`` + +Implement the RPC client +~~~~~~~~~~~~~~~~~~~~~~~~ + +Implementing the RPC client uses the rpcgen generated .h files. The +remote method calls go in: + +``src/remote/remote_driver.c`` + +Each remote method invocation does the following: + +#. locks the remote driver; +#. sets up the method arguments; +#. invokes the remote function; +#. checks the return value, if necessary; +#. extracts any returned data; +#. frees any returned data; +#. unlocks the remote driver. + +Implement the server side dispatcher +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Implementing the server side of the remote function call is simply a +matter of deserializing the parameters passed in from the remote caller +and passing them to the corresponding internal API function. The server +side dispatchers are implemented in: + +``src/remote/remote_daemon_dispatch.c`` + +Again, this step uses the .h files generated by make rpcgen. + +After all three pieces of the remote protocol are complete, and the +generated files have been updated, it will be necessary to update the +file: + +``src/remote_protocol-structs`` + +This file should only have new lines added; modifications to existing +lines probably imply a backwards-incompatible API change. + +Use the new API internally +-------------------------- + +Sometimes, a new API serves as a superset of existing API, by adding +more granularity in what can be managed. When this is the case, it makes +sense to share a common implementation by making the older API become a +trivial wrapper around the new API, rather than duplicating the common +code. This step should not introduce any semantic differences for the +old API, and is not necessary if the new API has no relation to existing +API. + +Expose the new API in virsh +--------------------------- + +All new API should be manageable from the virsh command line shell. This +proves that the API is sufficient for the intended purpose, and helps to +identify whether the proposed API needs slight changes for easier usage. +However, remember that virsh is used to connect to hosts running older +versions of libvirtd, so new commands should have fallbacks to an older +API if possible; implementing the virsh hooks at this point makes it +very easy to test these fallbacks. Also remember to document virsh +additions. + +A virsh command is composed of a few pieces of code. You need to define +an array of vshCmdInfo structs for each new command that contain the +help text and the command description text. You also need an array of +vshCmdOptDef structs to describe the command options. Once you have +those pieces in place you can write the function implementing the virsh +command. Finally, you need to add the new command to the commands[] +array. The following files need changes: + +``tools/virsh-$MODULE.c tools/virsh.pod`` + +Implement the driver methods +---------------------------- + +So, after all that, we get to the fun part. All functionality in libvirt +is implemented inside a driver. Thus, here is where you implement +whatever functionality you're adding to libvirt. You'll either need to +add additional files to the src directory or extend files that are +already there, depending on what functionality you're adding. + +Implement common handling +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the new API is applicable to more than one driver, it may make sense +to provide some utility routines, or to factor some of the work into the +dispatcher, to avoid reimplementing the same code in every driver. In +the example code, this involved adding a member to the virDomainDefPtr +struct for mapping between the XML API addition and the in-memory +representation of a domain, along with updating all clients to use the +new member. Up to this point, there have been no changes to existing +semantics, and the new APIs will fail unless they are used in the same +way as the older API wrappers. + +Implement driver handling +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The remaining patches should only touch one driver at a time. It is +possible to implement all changes for a driver in one patch, but for +review purposes it may still make sense to break things into simpler +steps. Here is where the new APIs finally start working. + +It is always a good idea to patch the test driver in addition to the +target driver, to prove that the API can be used for more than one +driver. + +Any cleanups resulting from the changes should be added as separate +patches at the end of the series. + +Once you have working functionality, run ninja test on each patch of the +series before submitting patches. It may also be worth writing tests for +the libvirt-TCK testsuite to exercise your new API, although those +patches are not kept in the libvirt repository. diff --git a/docs/meson.build b/docs/meson.build index 0f402bbf6a..b031bd6717 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'api_extension', 'api', 'apps', 'architecture', @@ -107,6 +106,7 @@ docs_html_in_files =3D [ docs_rst_files =3D [ 'aclpolkit', 'advanced-tests', + 'api_extension', 'best-practices', 'ci', 'coding-style', --=20 2.29.2 From nobody Sun May 5 18:42:52 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=1615549501; cv=none; d=zohomail.com; s=zohoarc; b=T18UtHiRbuAddbzsOcuJMoIF5y/PmSks/iw2UzE1ioLm/GwlhYDNkPGHLiABe+7VhJfBpTDXEbGCqaPZlZTED78WTZYWWf+5RIm7AAD44VRlQFXMn+MozmBZ6ixkPb23/IrlEQM+NePTMLo0i/7Wj3fcyJx1FStiV+YrgzYPl3k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549501; h=Content-Type:Content-Transfer-Encoding:Cc: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=UmMobhepDUjtAHrLz6ziolH5b/ghrXUGelHxZ6bww+k=; b=MCfZwWvUrp0AlxeqjTbRp3yVZ8l9ffQ9fDmlhOr3nA8HGVNBJqSHbLkyVOQ8BHFij7T+4+NlCRkReLMvLf05U/zeIW2wRc2VNH7lDpnuOSOi2/UMfjY7G69mb3povjJTRynI4tiloZr2YgD9TeJmt/aBgmz0N3biBvwArAf0kEQ= 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) header.from= 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 1615549501843331.3927866245431; Fri, 12 Mar 2021 03:45:01 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-30-C6PaskOTOyKMc5Ldha8Lcg-1; Fri, 12 Mar 2021 06:44:58 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 5F09E1084C8C; Fri, 12 Mar 2021 11:44:53 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 360C45C1D5; Fri, 12 Mar 2021 11:44:53 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id B3C6B57DC4; Fri, 12 Mar 2021 11:44:52 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhKV9024853 for ; Fri, 12 Mar 2021 06:43:20 -0500 Received: by smtp.corp.redhat.com (Postfix) id 0F5FA9CA0; Fri, 12 Mar 2021 11:43:20 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 5DA2619813; Fri, 12 Mar 2021 11:43:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549500; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=UmMobhepDUjtAHrLz6ziolH5b/ghrXUGelHxZ6bww+k=; b=UIcrcYgZI0oRPlBfM875Sxw2AdWa05lPRUQ1CFtR81MDBVfZBg9pm55qKhNtxV4tUUYToi LdKMHFkjcGUoi6OF//4FIDdZ5kPDowRy3wVzHtTO4Pe+N8RzqVL/gIpfpfr+3iVjL0zMxH TtxuaoaPQVSycTfoLWuBpluZL0BySwg= X-MC-Unique: C6PaskOTOyKMc5Ldha8Lcg-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 3/9] docs: html.in: Convert api to rst Date: Fri, 12 Mar 2021 12:43:06 +0100 Message-Id: <929b6319e294d8820cf5215ab705e88de6dc61ac.1615549300.git.eskultet@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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) Content-Type: text/plain; charset="utf-8" There were a number of occurrences where we used nested inline markup (verbatim + refs) which is currently not possible with RST syntax [1]. There is a possible workaround involving substitution definitions like .. |virConnectPtr| replace:: ``virConnectPtr`` .. _virConnectPtr: /html/libvirt-libvirt-host.html#virConnectPtr Substitutions cannot be made generic, hence we cannot create a template for substitution and use a single template everywhere, so we'd end up with a lot of clutter and convolution. Therefore, we can make an exception and just link the data type without further style markup. [1] https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possib= le Signed-off-by: Erik Skultety Reviewed-by: Peter Krempa --- docs/api.html.in | 380 ----------------------------------------------- docs/api.rst | 265 +++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 266 insertions(+), 381 deletions(-) delete mode 100644 docs/api.html.in create mode 100644 docs/api.rst diff --git a/docs/api.html.in b/docs/api.html.in deleted file mode 100644 index 4bff037d48..0000000000 --- a/docs/api.html.in +++ /dev/null @@ -1,380 +0,0 @@ - - - - -

      The libvirt API concepts

      - -

      This page describes the main principles and architecture choices - behind the definition of the libvirt API:

      - -
        - -

        Objects Exposed

        -

        As defined in the goals section, the li= bvirt - API is designed to expose all the resources needed to manage the - virtualization support of recent operating systems. The first object - manipulated through the API is the virConnectPtr, which - represents the connection to a hypervisor. Any application using libvi= rt - is likely to start using the - API by calling one of the virConnectOpen functions. You will note that those functions = take - a name argument which is actually a connection UR= I - to select the right hypervisor to open. - A URI is needed to allow remote connections and also select between - different possible hypervisors. For example, on a Linux system it may = be - possible to use both KVM and LinuxContainers on the same node. A NULL - name will default to a preselected hypervisor, but it's probably not a - wise thing to do in most cases. See the connection - URI page for a full descriptions of the values allowed.

        -

        OnDevice the application obtains a - - virConnectPtr - - connection to the hypervisor it can then use it to manage the hypervis= or's - available domains and related virtualization - resources, such as storage and networking. All those are - exposed as first class objects and connected to the hypervisor connect= ion - (and the node or cluster where it is available).

        -

        - 3D"first -

        -

        The figure above shows the five main objects exported by the API:<= /p> -

        -

        Most objects manipulated by the library can also be represented us= ing - XML descriptions. This is used primarily to create those object, but= is - also helpful to modify or save their description back.

        -

        Domains, networks, and storage pools can be either active - i.e. either running or available for immediate use, or - defined in which case they are inactive but there is - a permanent definition available in the system for them. Based on th= is - they can be activated dynamically in order to be used.

        -

        Most objects can also be named in various ways:

        -
          -
        • name -

          A user friendly identifier but whose uniqueness - cannot be guaranteed between two nodes.

          • -
        • ID -

          A runtime unique identifier - provided by the hypervisor for one given activation of the object; - however, it becomes invalid once the resource is deactivated.

          -
        • UUID -

          A 16 byte unique identifier - as defined in RFC 4= 122, - which is guaranteed to be unique for long term usage and across a - set of nodes.

          • -
        - -

        Functions and Naming Conventions

        -

        The naming of the functions present in the library is usually - composed by a prefix describing the object associated to the function - and a verb describing the action on that object.

        -

        For each first class object you will find APIs - for the following actions:

        - -

        Note: functions returning vir*Ptr (like the virDomainLookup functio= ns) - allocate memory which needs to be freed by the caller by the correspon= ding - vir*Free function (e.g. virDomainFree for a virDomainPtr object). -

        -

        For more in-depth details of the storage related APIs see - the storage management page. -

        -

        The libvirt Drivers

        -

        Drivers are the basic building block for libvirt functionality - to support the capability to handle specific hypervisor driver calls. - Drivers are discovered and registered during connection processing as - part of the - - virInitialize - - API. Each driver - has a registration API which loads up the driver specific function - references for the libvirt APIs to call. The following is a simplistic - view of the hypervisor driver mechanism. Consider the stacked list of - drivers as a series of modules that can be plugged into the architectu= re - depending on how libvirt is configured to be built.

        -

        - 3D"The -

        -

        The driver architecture is also used to support other virtualization - components such as storage, storage pools, host device, networking, - network interfaces, and network filters.

        -

        See the libvirt drivers page for more - information on hypervisor and storage specific drivers.

        -

        Not all drivers support every virtualization function possible. - The libvirt API support matrix lists - the various functions and support found in each driver by the version - support was added into libvirt. -

        -

        Daemon and Remote Access

        -

        Access to libvirt drivers is primarily handled by the libvirtd - daemon through the remote driver via an - RPC. Some hypervisors do support - client-side connections and responses, such as Test, OpenVZ, VMware, - VirtualBox (vbox), ESX, Hyper-V, Xen, and Virtuozzo. - The libvirtd daemon service is started on the host at system boot - time and can also be restarted at any time by a properly privileged - user, such as root. The libvirtd daemon uses the same libvirt API - - virInitialize - - sequence as applications - for client-side driver registrations, but then extends the registered - driver list to encompass all known drivers supported for all driver - types supported on the host.

        -

        The libvirt client applications use a - URI to obtain the virConnectPtr. - The virConnectPtr keeps track of the driver connection - plus a variety of other connections (network, interface, storage, etc.= ). - The virConnectPtr is then used as a parameter to other - virtualization functions. Depending upon the - driver being used, calls will be routed through the remote driver to - the libvirtd daemon. The daemon will reference the connection specific - driver in order to retrieve the requested information and then pass - back status and/or data through the connection back to the application. - The application can then decide what to do with that data, such as - display, write log data, etc. Migration - is an example of many facets of the architecture in use.

        - -

        - 3D"The -

        -

        - The key takeaway from the above diagram is that there is a remote driv= er - which handles transactions for a majority of the drivers. The libvirtd - daemon running on the host will receive transaction requests from the - remote driver and will then query the hypervisor driver as specified in - the virConnectPtr in order to fetch the data. The data wi= ll - then be returned through the remote driver to the client application - for processing. -

        -

        If you are interested in contributing to libvirt, read the - FAQ and - hacking guidelines to gain an understandi= ng - of basic rules and guidelines. In order to add new API functionality - follow the instructions regarding - implementing a new API in libvirt. -

        - - - diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000000..a8f527e197 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,265 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +The libvirt API concepts +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This page describes the main principles and architecture choices behind +the definition of the libvirt API: + +.. contents:: + +Objects Exposed +--------------- + +As defined in the `goals section `__, the libvirt API is +designed to expose all the resources needed to manage the virtualization +support of recent operating systems. The first object manipulated +through the API is the ``virConnectPtr``, which represents the +connection to a hypervisor. Any application using libvirt is likely to +start using the API by calling one of `the virConnectOpen +functions `__. You will +note that those functions take a name argument which is actually a +`connection URI `__ to select the right hypervisor to open. A +URI is needed to allow remote connections and also select between +different possible hypervisors. For example, on a Linux system it may be +possible to use both KVM and LinuxContainers on the same node. A NULL +name will default to a preselected hypervisor, but it's probably not a +wise thing to do in most cases. See the `connection URI `__ +page for a full descriptions of the values allowed. + +OnDevice the application obtains a +`virConnectPtr `__ +connection to the hypervisor it can then use it to manage the +hypervisor's available domains and related virtualization resources, +such as storage and networking. All those are exposed as first class +objects and connected to the hypervisor connection (and the node or +cluster where it is available). + +|first class objects exposed by the API| + +The figure above shows the five main objects exported by the API: + +- `virConnectPtr `__ + + Represents the connection to a hypervisor. Use one of the + `virConnectOpen `__ + functions to obtain connection to the hypervisor which is then used + as a parameter to other connection API's. + +- `virDomainPtr `__ + + Represents one domain either active or defined (i.e. existing as + permanent config file and storage but not currently running on that + node). The function + `virConnectListAllDomains `__ + lists all the domains for the hypervisor. + +- `virNetworkPtr `__ + + Represents one network either active or defined (i.e. existing as + permanent config file and storage but not currently activated). The + function + `virConnectListAllNetworks `__ + lists all the virtualization networks for the hypervisor. + +- `virStorageVolPtr `= __ + + Represents one storage volume generally used as a block device + available to one of the domains. The function + `virStorageVolLookupByPath `__ + finds the storage volume object based on its path on the node. + +- `virStoragePoolPtr `__ + + Represents a storage pool, which is a logical area used to allocate + and store storage volumes. The function + `virConnectListAllStoragePools `__ + lists all of the virtualization storage pools on the hypervisor. The + function + `virStoragePoolLookupByVolume `__ + finds the storage pool containing a given storage volume. + +Most objects manipulated by the library can also be represented using +XML descriptions. This is used primarily to create those object, but is +also helpful to modify or save their description back. + +Domains, networks, and storage pools can be either ``active`` i.e. +either running or available for immediate use, or ``defined`` in which +case they are inactive but there is a permanent definition available in +the system for them. Based on this they can be activated dynamically in +order to be used. + +Most objects can also be named in various ways: + +- ``name`` + + A user friendly identifier but whose uniqueness cannot be guaranteed + between two nodes. + +- ``ID`` + + A runtime unique identifier provided by the hypervisor for one given + activation of the object; however, it becomes invalid once the + resource is deactivated. + +- ``UUID`` + + A 16 byte unique identifier as defined in `RFC + 4122 `__, which is guaranteed + to be unique for long term usage and across a set of nodes. + +Functions and Naming Conventions +-------------------------------- + +The naming of the functions present in the library is usually composed +by a prefix describing the object associated to the function and a verb +describing the action on that object. + +For each first class object you will find APIs for the following +actions: + +- **Lookup** [...LookupBy...] + + Used to perform lookups on objects by some type of identifier, such + as: + + - `virDomainLookupByID `__ + - `virDomainLookupByName `__ + - `virDomainLookupByUUID `__ + - `virDomainLookupByUUIDString `__ + +- **Enumeration** [virConnectList..., virConnectNumOf...] + + Used to enumerate a set of object available to a given hypervisor + connection such as: + + - `virConnectListDomains `__ + - `virConnectNumOfDomains `__ + - `virConnectListNetworks `__ + - `virConnectListStoragePools `__ + +- **Description** [...GetInfo] + + Generic accessor providing a set of generic information about an + object, such as: + + - `virNodeGetInfo `__ + - `virDomainGetInfo `__ + - `virStoragePoolGetInfo `__ + - `virStorageVolGetInfo `__ + +- **Accessors** [...Get..., ...Set...] + + Specific accessors used to query or modify data for the given object, + such as: + + - `virConnectGetType `__ + - `virDomainGetMaxMemory `__ + - `virDomainSetMemory `__ + - `virDomainGetVcpus `__ + - `virStoragePoolSetAutostart `__ + - `virNetworkGetBridgeName `__ + +- **Creation** [...Create, ...CreateXML] + + Used to create and start objects. The ...CreateXML APIs will create + the object based on an XML description, while the ...Create APIs will + create the object based on existing object pointer, such as: + + - `virDomainCreate `= __ + - `virDomainCreateXML `__ + - `virNetworkCreate `__ + - `virNetworkCreateXML `__ + +- **Destruction** [...Destroy] + + Used to shutdown or deactivate and destroy objects, such as: + + - `virDomainDestroy `__ + - `virNetworkDestroy `__ + - `virStoragePoolDestroy `__ + +Note: functions returning vir*Ptr (like the virDomainLookup functions) +allocate memory which needs to be freed by the caller by the +corresponding vir*Free function (e.g. virDomainFree for a virDomainPtr +object). + +For more in-depth details of the storage related APIs see `the storage +management page `__. + +The libvirt Drivers +------------------- + +Drivers are the basic building block for libvirt functionality to +support the capability to handle specific hypervisor driver calls. +Drivers are discovered and registered during connection processing as +part of the +`virInitialize `__ +API. Each driver has a registration API which loads up the driver +specific function references for the libvirt APIs to call. The following +is a simplistic view of the hypervisor driver mechanism. Consider the +stacked list of drivers as a series of modules that can be plugged into +the architecture depending on how libvirt is configured to be built. + +|The libvirt driver architecture| + +The driver architecture is also used to support other virtualization +components such as storage, storage pools, host device, networking, +network interfaces, and network filters. + +See the `libvirt drivers `__ page for more information on +hypervisor and storage specific drivers. + +Not all drivers support every virtualization function possible. The +`libvirt API support matrix `__ lists the various +functions and support found in each driver by the version support was +added into libvirt. + +Daemon and Remote Access +------------------------ + +Access to libvirt drivers is primarily handled by the libvirtd daemon +through the `remote `__ driver via an +`RPC `__. Some hypervisors do support client-side +connections and responses, such as Test, OpenVZ, VMware, VirtualBox +(vbox), ESX, Hyper-V, Xen, and Virtuozzo. The libvirtd daemon service is +started on the host at system boot time and can also be restarted at any +time by a properly privileged user, such as root. The libvirtd daemon +uses the same libvirt API +`virInitialize `__ +sequence as applications for client-side driver registrations, but then +extends the registered driver list to encompass all known drivers +supported for all driver types supported on the host. + +The libvirt client `applications `__ use a `URI `__ +to obtain the ``virConnectPtr``. The ``virConnectPtr`` keeps track of +the driver connection plus a variety of other connections (network, +interface, storage, etc.). The ``virConnectPtr`` is then used as a +parameter to other virtualization `functions <#Functions>`__. Depending +upon the driver being used, calls will be routed through the remote +driver to the libvirtd daemon. The daemon will reference the connection +specific driver in order to retrieve the requested information and then +pass back status and/or data through the connection back to the +application. The application can then decide what to do with that data, +such as display, write log data, etc. `Migration `__ is +an example of many facets of the architecture in use. + +|The libvirt daemon and remote architecture| + +The key takeaway from the above diagram is that there is a remote driver +which handles transactions for a majority of the drivers. The libvirtd +daemon running on the host will receive transaction requests from the +remote driver and will then query the hypervisor driver as specified in +the ``virConnectPtr`` in order to fetch the data. The data will then be +returned through the remote driver to the client application for +processing. + +If you are interested in contributing to libvirt, read the +`FAQ `__ and +`hacking `__ guidelines to gain an understanding of basic +rules and guidelines. In order to add new API functionality follow the +instructions regarding `implementing a new API in +libvirt `__. + +.. |first class objects exposed by the API| image:: libvirt-object-model.p= ng +.. |The libvirt driver architecture| image:: libvirt-driver-arch.png +.. |The libvirt daemon and remote architecture| image:: libvirt-daemon-arc= h.png diff --git a/docs/meson.build b/docs/meson.build index b031bd6717..942cce6fdc 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'api', 'apps', 'architecture', 'auditlog', @@ -107,6 +106,7 @@ docs_rst_files =3D [ 'aclpolkit', 'advanced-tests', 'api_extension', + 'api', 'best-practices', 'ci', 'coding-style', --=20 2.29.2 From nobody Sun May 5 18:42:52 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.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 216.205.24.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=1615549564; cv=none; d=zohomail.com; s=zohoarc; b=e61gBiqFcLfNYNrQ+6B4V3+z5o8nLoGCEifJM2baZErfu024TSY+5jEnkXcYcVq+wOPZz1SLb7HS2C161VmJ/8GoR/ja2/IlQN8d9ybeKn2sJioWMzAHe2qrKeW1u63JjzJ1uCT/N8w5vjoCy8CvUqeNLm3TdHDodFdHcIO/6d8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549564; h=Content-Type:Content-Transfer-Encoding:Cc: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=kdngHhLEKCDV+a2kJXmY2gcQTsgjxaPMrq9L1O5qh1Q=; b=egKCIf8MEy4VdBBQi+lc8QG+9iOrmftJjoNkq8EMlxk+E7KMQF0ikMp9nZUoyx9ZASjWauOQM0E1sYrqCc33WYuBEP9Y3gah0MJIYJF7GaNvwOx/nP7GFNE+tVEjVbvednanYUqpUZ+1JwC8G8foW/oTHi0t4W6Gh4IVcSHKYKs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1615549564132893.6795097259851; Fri, 12 Mar 2021 03:46:04 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-438-8GCSpWuHMrKEjUWu3tQ2pA-1; Fri, 12 Mar 2021 06:45:04 -0500 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 884A2100C61A; Fri, 12 Mar 2021 11:44:59 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 3B9B45DDAD; Fri, 12 Mar 2021 11:44:59 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 020CA57DC1; Fri, 12 Mar 2021 11:44:59 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhLen024868 for ; Fri, 12 Mar 2021 06:43:21 -0500 Received: by smtp.corp.redhat.com (Postfix) id 13F8C60636; Fri, 12 Mar 2021 11:43:21 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 5F62719813; Fri, 12 Mar 2021 11:43:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549563; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=kdngHhLEKCDV+a2kJXmY2gcQTsgjxaPMrq9L1O5qh1Q=; b=V4cNRXV8QgucDHEUfdeg2VY3yZSTnK9mmGUol36crvk4+RUKy5m8vE+lc/od42Iw1oT5Qd 02QJKz/tnOHhKyZQipyc3qt80lda/8fZWv0MS3UxIkh3ccS5ygzMDrQWmZPe/4kGU6weBU 8+qKAJeVsAaxwqs+6FuYirKA15y/TxM= X-MC-Unique: 8GCSpWuHMrKEjUWu3tQ2pA-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 4/9] docs: html.in: Convert apps to rst Date: Fri, 12 Mar 2021 12:43:07 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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) Signed-off-by: Erik Skultety Reviewed-by: Peter Krempa --- docs/apps.html.in | 488 ---------------------------------------------- docs/apps.rst | 348 +++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 349 insertions(+), 489 deletions(-) delete mode 100644 docs/apps.html.in create mode 100644 docs/apps.rst diff --git a/docs/apps.html.in b/docs/apps.html.in deleted file mode 100644 index bac1e36365..0000000000 --- a/docs/apps.html.in +++ /dev/null @@ -1,488 +0,0 @@ - - - - -

        Applications using libvirt

        - -

        - This page provides an illustration of the wide variety of - applications using the libvirt management API. -

        - -
          - -

          Add an application

          - -

          - To add an application not listed on this page, send a message - to the mailing list, requesting it - be added here, or simply send a patch against the documentation - in the libvirt.git docs subdirectory. - If your application uses libvirt as its API, - the following graphics are available for your website to advertise - support for libvirt: -

          - -

          - 3D"libvirt - 3D"libvirt - 3D"libvirt -

          - -

          Command line tools

          - -
          -
          guestfish
          -
          - Guestfish is an interactive shell and command-line tool for examin= ing - and modifying virtual machine filesystems. It uses libvirt to find - guests and their associated disks. -
          -
          virsh
          -
          - An interactive shell, and batch scriptable tool for performing - management tasks on all libvirt managed domains, networks and - storage. This is part of the libvirt core distribution. -
          -
          virt-clone
          -
          - Allows the disk image(s) and configuration for an existing - virtual machine to be cloned to form a new virtual machine. - It automates copying of data across to new disk images, and - updates the UUID, MAC address, and name in the configuration. -
          -
          virt-df
          -
          - Examine the utilization of each filesystem in a virtual machine - from the comfort of the host machine. This tool peeks into the - guest disks and determines how much space is used. It can cope - with common Linux filesystems and LVM volumes. -
          -
          virt-image
          -
          - Provides a way to deploy virtual appliances. It defines a - simplified portable XML format describing the pre-requisites - of a virtual machine. At time of deployment this is translated - into the domain XML format for execution under any libvirt - hypervisor meeting the pre-requisites. -
          -
          virt-install
          -
          - Provides a way to provision new virtual machines from a - OS distribution install tree. It supports provisioning from - local CD images, and the network over NFS, HTTP and FTP. -
          -
          virt-top<= /a>
          -
          - Watch the CPU, memory, network and disk utilization of all - virtual machines running on a host. -
          -
          - virt-what= -
          -
          - virt-what is a shell script for detecting if the program is running - in a virtual machine. It prints out a list of facts about the - virtual machine, derived from heuristics. -
          -
          stap
          -
          - SystemTap is a tool used to gather rich information about a running - system through the use of scripts. Starting from v2.4, the front-e= nd - application stap can use libvirt to gather data within virtual - machines. -
          -
          vagrant-= libvirt
          -
          - Vagrant-Libvirt is a Vagrant plugin that uses libvirt to manage vi= rtual - machines. It is a command line tool for developers that makes it v= ery - fast and easy to deploy and re-deploy an environment of vm's. -
          -
          vir= t-lightning
          -
          - Virt-Lightning uses libvirt, cloud-init and libguestfs to allow an= yone - to quickly start a new VM. Very much like a container CLI, but wit= h a - virtual machine. -
          -
          - -

          Configuration Management

          - -
          -
          LCFG=
          -
          - LCFG is a system for automatically installing and managing the - configuration of large numbers of Unix systems. It is particularly - suitable for sites with very diverse and rapidly changing - configurations. -
          -
          - The lcfg-libvirt package adds support for virtualized systems to - LCFG, with both Xen and KVM known to work. Cloning guests is - supported, as are the bridged, routed, and isolated modes for - Virtual Networking. -
          -
          - -

          Continuous Integration

          - -
          -
          BuildBot
          -
          - BuildBot is a system to automate the compile/test cycle required - by most software projects. CVS commits trigger new builds, run on - a variety of client machines. Build status (pass/fail/etc) are - displayed on a web page or through other protocols. -
          -
          - -
          -
          Jenkins
          -
          - This plugin for Jenkins adds a way to control guest domains hosted - on Xen or QEMU/KVM. You configure a Jenkins Agent, - selecting the guest domain and hypervisor. When you need to build= a - job on a specific Agent, its guest domain is started, then the job= is - run. When the build process is finished, the guest domain is shut - down, ready to be used again as required. -
          -
          - -

          Conversion

          - -
          -
          virt-p2v<= /dt> -
          - Convert a physical machine to run on KVM. It is a LiveCD - which is booted on the machine to be converted. It collects a - little information from the user, then copies the disks over - to a remote machine and defines the XML for a domain to run - the guest. (Note this tool is included with libguestfs) -
          -
          virt-v2v<= /dt> -
          - virt-v2v converts guests from a foreign hypervisor to run on - KVM, managed by libvirt. It can convert guests from VMware or - Xen to run on OpenStack, oVirt (RHEV-M), or local libvirt. It - will enable VirtIO drivers in the converted guest if possible. - (Note this tool is included with libguestfs) -
          -
          - For RHEL customers of Red Hat, conversion of Windows guests is also - possible. This conversion requires some Microsoft signed pieces, - that Red Hat can provide. -
          -
          vmware2libvirt
          -
          - Part of the virt-goodies package, vmware2libvirt is a python - script for migrating a vmware image to libvirt. -
          -
          - -

          Desktop applications

          - -
          -
          virt-manager
          -
          - A general purpose desktop management tool, able to manage - virtual machines across both local and remotely accessed - hypervisors. It is targeted at home and small office usage - up to managing 10-20 hosts and their VMs. -
          -
          virt-viewer
          -
          - A lightweight tool for accessing the graphical console - associated with a virtual machine. It can securely connect - to remote consoles supporting the VNC protocol. Also provides - an optional mozilla browser plugin. -
          -
          qt-virt-mana= ger
          -
          - The Qt GUI for create and control VMs and another virtual entities - (aka networks, storages, interfaces, secrets, network filters). - Contains integrated LXC/SPICE/VNC viewer for accessing the graphic= al or - text console associated with a virtual machine or container. -
          -
          qt-remote-viewer
          -
          - The Qt VNC/SPICE viewer for access to remote desktops or VMs. -
          -
          - -

          Infrastructure as a Service (IaaS)

          - -
          -
          Cracow Cloud One
          -
          The CC1 system provides a complete solution for Private - Cloud Computing. An intuitive web access interface with an - administration module and simple installation procedure make - it easy to benefit from private Cloud Computing technology. -
          - -
          Eucalyptus<= /a>
          -
          - Eucalyptus is an on-premise Infrastructure as a Service cloud - software platform that is open source and - AWS-compatible. Eucalyptus uses libvirt virtualization API to - directly interact with Xen and KVM hypervisors. -
          - -
          Nimbus
          -
          - Nimbus is an open-source toolkit focused on providing - Infrastructure-as-a-Service (IaaS) capabilities to the scientific - community. It uses libvirt for communication with all KVM and Xen - virtual machines. -
          - -
          Snooze
          -
          - Snooze is an open-source scalable, autonomic, and energy-efficient - virtual machine (VM) management framework for private clouds. It - integrates libvirt for VM monitoring, live migration, and life-cyc= le - management. -
          - -
          OpenStack
          -
          - OpenStack is a "cloud operating system" usable for both public - and private clouds. Its various parts take care of compute, - storage and networking resources and interface with the user - using a dashboard. Compute part uses libvirt to manage VM - life-cycle, monitoring and so on. -
          - -
          KubeVirt
          -
          - KubeVirt is a virtual machine management add-on for Kubernetes. Th= e aim - is to provide a common ground for virtualization solutions on top = of - Kubernetes. -
          - -
          Ch= errypop
          -
          - A cloud software with no masters or central points. Nodes - autodetect other nodes and autodistribute virtual - machines and autodivide up the workload. Also there is no - minimum limit for hosts, well, one might be nice. It's - perfect for setting up low-end servers in a cloud or a - cloud where you want the most bang for the bucks. -
          - -
          ZStack
          -
          - ZStack is an open source IaaS software that aims to automate the - management of all resources (compute, storage, networking, etc.) i= n a - datacenter by using APIs, thus conforming to the principles of a - software-defined datacenter. The key strengths of ZStack in terms = of - management are scalability, performance, and a fast, user-friendly - deployment. -
          -
          - -

          Libraries

          - -
          -
          libguestfs
          -
          - A library and set of tools for accessing and modifying virtual - machine disk images. It can be linked with C and C++ management - programs, and has bindings for Perl, Python, Ruby, Java, OCaml, - PHP, Haskell, and C#. -
          -
          - Using its FUSE module, you can also mount guest filesystems on the - host, and there is a subproject to allow merging changes into the - Windows Registry in Windows guests. -
          - -
          libvirt-sandbox
          -
          - A library and command line tools for simplifying the creation of - application sandboxes using virtualization technology. It currently - supports either KVM, QEMU or LXC as backends. Integration with - systemd facilitates sandboxing of system services like apache. -
          -
          Ruby - Libvirt Object bindings
          -
          - Allows using simple ruby objects to manipulate - hypervisors, guests, storage, network etc. It is - based on top of - the native ruby bindings. -
          -
          - -

          LiveCD / Appliances

          - -
          -
          virt-p2v
          -
          - An older tool for converting a physical machine into a virtual - machine. It is a LiveCD which is booted on the machine to be - converted. It collects a little information from the user, then - copies the disks over to a remote machine and defines the XML for a - domain to run the guest. -
          -
          - -

          Monitoring

          -
          -
          collectd<= /a>
          -
          - The libvirt-plugin is part of co= llectd - and gathers statistics about virtualized guests on a system. This - way, you can collect CPU, network interface and block device usage - for each guest without installing collectd on the guest systems. - For a full description, please refer to the libvirt section in the - collectd.conf(5) manual page. -
          -
          Host sFlow
          -
          - Host sFlow is a lightweight agent running on KVM hypervisors that - links to libvirt library and exports standardized cpu, memory, net= work - and disk metrics for all virtual machines. -
          -
          Mun= in
          -
          - The plugins provided by Guido G=C3=BCnther allow to monitor variou= s things - like network and block I/O with - Munin. -
          -
          Nagios= -virt
          -
          - Nagios-virt is a configuration tool to add monitoring of your - virtualised domains to Nagios<= /a>. - You can use this tool to either set up a new Nagios installation f= or - your Xen or QEMU/KVM guests, or to integrate with your existing Na= gios - installation. -
          -
          PCP -
          - The PCP libvirt PMDA (plugin) is part of the - PCP toolkit and provides - hypervisor and guest information and complete set of guest perform= ance - metrics. It supports pCPU, vCPU, memory, block device, network int= erface, - and performance event metrics for each virtual guest. -
          -
          - -

          Provisioning

          - -
          -
          Tivoli Provisioning Manage= r
          -
          - Part of the IBM Tivoli family, Tivoli Provisioning Manager (TPM) is - an IT lifecycle automation product. It - uses l= ibvirt - for communication with virtualization hosts and guest domains. -
          -
          - -
          -
          Foreman
          -
          - Foreman is an open source web based application aimed to be a - Single Address For All Machines Life Cycle Management. Foreman: - -
            -
          • Creates everything you need when adding a new machine to - your network, its goal being automatically managing - everything you would normally manage manually (DNS, DHCP, - TFTP, Virtual Machines,CA, CMDB...)
            • -
          • Integrates with Puppet (and acts as web front end to it). -
          • Takes care of provisioning until the point puppet is - running, allowing Puppet to do what it does best.
            • -
          • Shows you Systems Inventory (based on Facter) and - provides real time information about hosts status based on - Puppet reports.
            • -
          -
          -
          - - -

          Web applications

          - -
          -
          AbiCloud
          -
          - AbiCloud is an open source cloud platform manager which allows to - easily deploy a private cloud in your datacenter. One of the key - differences of AbiCloud is the web rich interface for managing the - infrastructure. You can deploy a new service just dragging and - dropping a VM. -
          -
          Kimchi<= /dt> -
          - Kimchi is an HTML5 based management tool for KVM. It is designed to - make it as easy as possible to get started with KVM and create you= r first guest. - - Kimchi manages KVM guests through libvirt. The management interfac= e is accessed - over the web using a browser that supports HTML5. -
          -
          oVirt
          -
          - oVirt provides the ability to manage large numbers of virtual - machines across an entire data center of hosts. It integrates - with FreeIPA for Kerberos authentication, and in the future, - certificate management. -
          -
          VMmanage= r
          -
          - VMmanager is a software solution for virtualization management - that can be used both for hosting virtual machines and - building a cloud. VMmanager can manage not only one server, - but a large cluster of hypervisors. It delivers a number of - functions, such as live migration that allows for load - balancing between cluster nodes, monitoring CPU, memory. -
          -
          mist.io
          -
          - Mist.io is an open source project and a service that can assist yo= u in - managing your virtual machines on a unified way, providing a simple - interface for all of your infrastructure (multiple public cloud - providers, OpenStack based public/private clouds, Docker servers, = bare - metal servers and now KVM hypervisors). -
          -
          Ravada
          -
          - Ravada is an open source tool for managing Virtual Desktop - Infrastructure (VDI). It is very easy to install and use. Following - the documentation, you'll be ready to deploy virtual machines in - minutes. The only requirements for the users are a Web browser and - a lightweight remote viewer. -
          -
          Virtlyst -
          - Virtlyst is an open source web application built with C++11, Cutel= yst and Qt. - It features: -
            -
          • Low memory usage (around 5 MiB of RAM)
            • -
          • Look and feel easily customized with HTML templates that use= the Django syntax
            • -
          • VNC/Spice console directly in the browser using websockets o= n the same HTTP port
            • -
          • Host and Domain statistics graphs (CPU, Memory, IO, Network)=
            • -
          • Connect to multiple libvirtd instances (over local Unix doma= in socket, SSH, TCP and TLS)
            • -
          • Manage Storage Pools, Storage Volumes, Networks, Interfaces,= and Secrets
            • -
          • Create and launch VMs
            • -
          • Configure VMs with easy panels or go pro and edit the VM's X= ML
            • -
          -
          -
          - -

          Other

          - -
          -
          Cuckoo Sandbox
          -
          - Cuckoo Sandbox is a malware analysis system. You can throw - any suspicious file at it and in a matter of seconds Cuckoo - will provide you back some detailed results outlining what - such file did when executed inside an isolated environment. - And libvirt is one of the backends that can be used for the - isolated environment. -
          -
          - - - diff --git a/docs/apps.rst b/docs/apps.rst new file mode 100644 index 0000000000..a21e2249ea --- /dev/null +++ b/docs/apps.rst @@ -0,0 +1,348 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D +Applications using libvirt +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D + +This page provides an illustration of the wide variety of applications +using the libvirt management API. + +.. contents:: + +Add an application +------------------ + +To add an application not listed on this page, send a message to the +`mailing list `__, requesting it be added here, or simply +send a patch against the documentation in the libvirt.git docs +subdirectory. If your application uses libvirt as its API, the following +graphics are available for your website to advertise support for +libvirt: + +|libvirt powered 96| |libvirt powered 128| |libvirt powered 192| |libvirt = powered 256| + +Command line tools +------------------ + +`guestfish `__ + Guestfish is an interactive shell and command-line tool for examining + and modifying virtual machine filesystems. It uses libvirt to find + guests and their associated disks. +virsh + An interactive shell, and batch scriptable tool for performing + management tasks on all libvirt managed domains, networks and + storage. This is part of the libvirt core distribution. +`virt-clone `__ + Allows the disk image(s) and configuration for an existing virtual + machine to be cloned to form a new virtual machine. It automates + copying of data across to new disk images, and updates the UUID, MAC + address, and name in the configuration. +`virt-df `__ + Examine the utilization of each filesystem in a virtual machine from + the comfort of the host machine. This tool peeks into the guest disks + and determines how much space is used. It can cope with common Linux + filesystems and LVM volumes. +`virt-image `__ + Provides a way to deploy virtual appliances. It defines a simplified + portable XML format describing the pre-requisites of a virtual + machine. At time of deployment this is translated into the domain XML + format for execution under any libvirt hypervisor meeting the + pre-requisites. +`virt-install `__ + Provides a way to provision new virtual machines from a OS + distribution install tree. It supports provisioning from local CD + images, and the network over NFS, HTTP and FTP. +`virt-top `__ + Watch the CPU, memory, network and disk utilization of all virtual + machines running on a host. +`virt-what `__ + virt-what is a shell script for detecting if the program is running + in a virtual machine. It prints out a list of facts about the virtual + machine, derived from heuristics. +`stap `__ + SystemTap is a tool used to gather rich information about a running + system through the use of scripts. Starting from v2.4, the front-end + application stap can use libvirt to gather data within virtual + machines. +`vagrant-libvirt `__ + Vagrant-Libvirt is a Vagrant plugin that uses libvirt to manage + virtual machines. It is a command line tool for developers that makes + it very fast and easy to deploy and re-deploy an environment of vm's. +`virt-lightning `__ + Virt-Lightning uses libvirt, cloud-init and libguestfs to allow + anyone to quickly start a new VM. Very much like a container CLI, but + with a virtual machine. + +Configuration Management +------------------------ + +`LCFG `__ + LCFG is a system for automatically installing and managing the + configuration of large numbers of Unix systems. It is particularly + suitable for sites with very diverse and rapidly changing + configurations. + The lcfg-libvirt package adds support for virtualized systems to + LCFG, with both Xen and KVM known to work. Cloning guests is + supported, as are the bridged, routed, and isolated modes for Virtual + Networking. + +Continuous Integration +---------------------- + +`BuildBot `__ + BuildBot is a system to automate the compile/test cycle required by + most software projects. CVS commits trigger new builds, run on a + variety of client machines. Build status (pass/fail/etc) are + displayed on a web page or through other protocols. + +`Jenkins `__ + This plugin for Jenkins adds a way to control guest domains hosted on + Xen or QEMU/KVM. You configure a Jenkins Agent, selecting the guest + domain and hypervisor. When you need to build a job on a specific + Agent, its guest domain is started, then the job is run. When the + build process is finished, the guest domain is shut down, ready to be + used again as required. + +Conversion +---------- + +`virt-p2v `__ + Convert a physical machine to run on KVM. It is a LiveCD which is + booted on the machine to be converted. It collects a little + information from the user, then copies the disks over to a remote + machine and defines the XML for a domain to run the guest. (Note this + tool is included with libguestfs) +`virt-v2v `__ + virt-v2v converts guests from a foreign hypervisor to run on KVM, + managed by libvirt. It can convert guests from VMware or Xen to run + on OpenStack, oVirt (RHEV-M), or local libvirt. It will enable VirtIO + drivers in the converted guest if possible. (Note this tool is + included with libguestfs) + For RHEL customers of Red Hat, conversion of Windows guests is also + possible. This conversion requires some Microsoft signed pieces, that + Red Hat can provide. +`vmware2libvirt `__ + Part of the *virt-goodies* package, vmware2libvirt is a python script + for migrating a vmware image to libvirt. + +Desktop applications +-------------------- + +`virt-manager `__ + A general purpose desktop management tool, able to manage virtual + machines across both local and remotely accessed hypervisors. It is + targeted at home and small office usage up to managing 10-20 hosts + and their VMs. +`virt-viewer `__ + A lightweight tool for accessing the graphical console associated + with a virtual machine. It can securely connect to remote consoles + supporting the VNC protocol. Also provides an optional mozilla + browser plugin. +`qt-virt-manager `__ + The Qt GUI for create and control VMs and another virtual entities + (aka networks, storages, interfaces, secrets, network filters). + Contains integrated LXC/SPICE/VNC viewer for accessing the graphical + or text console associated with a virtual machine or container. +`qt-remote-viewer `__ + The Qt VNC/SPICE viewer for access to remote desktops or VMs. + +Infrastructure as a Service (IaaS) +---------------------------------- + +`Cracow Cloud One `__ + The CC1 system provides a complete solution for Private Cloud + Computing. An intuitive web access interface with an administration + module and simple installation procedure make it easy to benefit from + private Cloud Computing technology. +`Eucalyptus `__ + Eucalyptus is an on-premise Infrastructure as a Service cloud + software platform that is open source and AWS-compatible. Eucalyptus + uses libvirt virtualization API to directly interact with Xen and KVM + hypervisors. +`Nimbus `__ + Nimbus is an open-source toolkit focused on providing + Infrastructure-as-a-Service (IaaS) capabilities to the scientific + community. It uses libvirt for communication with all KVM and Xen + virtual machines. +`Snooze `__ + Snooze is an open-source scalable, autonomic, and energy-efficient + virtual machine (VM) management framework for private clouds. It + integrates libvirt for VM monitoring, live migration, and life-cycle + management. +`OpenStack `__ + OpenStack is a "cloud operating system" usable for both public and + private clouds. Its various parts take care of compute, storage and + networking resources and interface with the user using a dashboard. + Compute part uses libvirt to manage VM life-cycle, monitoring and so + on. +`KubeVirt `__ + KubeVirt is a virtual machine management add-on for Kubernetes. The + aim is to provide a common ground for virtualization solutions on top + of Kubernetes. +`Cherrypop `__ + A cloud software with no masters or central points. Nodes autodetect + other nodes and autodistribute virtual machines and autodivide up the + workload. Also there is no minimum limit for hosts, well, one might + be nice. It's perfect for setting up low-end servers in a cloud or a + cloud where you want the most bang for the bucks. +`ZStack `__ + ZStack is an open source IaaS software that aims to automate the + management of all resources (compute, storage, networking, etc.) in a + datacenter by using APIs, thus conforming to the principles of a + software-defined datacenter. The key strengths of ZStack in terms of + management are scalability, performance, and a fast, user-friendly + deployment. + +Libraries +--------- + +`libguestfs `__ + A library and set of tools for accessing and modifying virtual + machine disk images. It can be linked with C and C++ management + programs, and has bindings for Perl, Python, Ruby, Java, OCaml, PHP, + Haskell, and C#. + Using its FUSE module, you can also mount guest filesystems on the + host, and there is a subproject to allow merging changes into the + Windows Registry in Windows guests. +`libvirt-sandbox `__ + A library and command line tools for simplifying the creation of + application sandboxes using virtualization technology. It currently + supports either KVM, QEMU or LXC as backends. Integration with + systemd facilitates sandboxing of system services like apache. +`Ruby Libvirt Object bindings `__ + Allows using simple ruby objects to manipulate hypervisors, guests, + storage, network etc. It is based on top of the `native ruby + bindings `__. + +LiveCD / Appliances +------------------- + +`virt-p2v `__ + An older tool for converting a physical machine into a virtual + machine. It is a LiveCD which is booted on the machine to be + converted. It collects a little information from the user, then + copies the disks over to a remote machine and defines the XML for a + domain to run the guest. + +Monitoring +---------- + +`collectd `__ + The libvirt-plugin is part of `collectd `__ + and gathers statistics about virtualized guests on a system. This + way, you can collect CPU, network interface and block device usage + for each guest without installing collectd on the guest systems. For + a full description, please refer to the libvirt section in the + collectd.conf(5) manual page. +`Host sFlow `__ + Host sFlow is a lightweight agent running on KVM hypervisors that + links to libvirt library and exports standardized cpu, memory, + network and disk metrics for all virtual machines. +`Munin `__ + The plugins provided by Guido G=C3=BCnther allow to monitor various thi= ngs + like network and block I/O with + `Munin `__. +`Nagios-virt `__ + Nagios-virt is a configuration tool to add monitoring of your + virtualised domains to `Nagios `__. You can + use this tool to either set up a new Nagios installation for your Xen + or QEMU/KVM guests, or to integrate with your existing Nagios + installation. +`PCP `__ + The PCP libvirt PMDA (plugin) is part of the + `PCP `__ toolkit and provides hypervisor and guest + information and complete set of guest performance metrics. It + supports pCPU, vCPU, memory, block device, network interface, and + performance event metrics for each virtual guest. + +Provisioning +------------ + +`Tivoli Provisioning Manager `__ + Part of the IBM Tivoli family, Tivoli Provisioning Manager (TPM) is + an IT lifecycle automation product. It `uses + libvirt `__ + for communication with virtualization hosts and guest domains. + +`Foreman `__ + Foreman is an open source web based application aimed to be a Single + Address For All Machines Life Cycle Management. Foreman: + + - Creates everything you need when adding a new machine to your + network, its goal being automatically managing everything you + would normally manage manually (DNS, DHCP, TFTP, Virtual + Machines,CA, CMDB...) + - Integrates with Puppet (and acts as web front end to it). + - Takes care of provisioning until the point puppet is running, + allowing Puppet to do what it does best. + - Shows you Systems Inventory (based on Facter) and provides real + time information about hosts status based on Puppet reports. + +Web applications +---------------- + +`AbiCloud `__ + AbiCloud is an open source cloud platform manager which allows to + easily deploy a private cloud in your datacenter. One of the key + differences of AbiCloud is the web rich interface for managing the + infrastructure. You can deploy a new service just dragging and + dropping a VM. +`Kimchi `__ + Kimchi is an HTML5 based management tool for KVM. It is designed to + make it as easy as possible to get started with KVM and create your + first guest. Kimchi manages KVM guests through libvirt. The + management interface is accessed over the web using a browser that + supports HTML5. +`oVirt `__ + oVirt provides the ability to manage large numbers of virtual + machines across an entire data center of hosts. It integrates with + FreeIPA for Kerberos authentication, and in the future, certificate + management. +`VMmanager `__ + VMmanager is a software solution for virtualization management that + can be used both for hosting virtual machines and building a cloud. + VMmanager can manage not only one server, but a large cluster of + hypervisors. It delivers a number of functions, such as live + migration that allows for load balancing between cluster nodes, + monitoring CPU, memory. +`mist.io `__ + Mist.io is an open source project and a service that can assist you + in managing your virtual machines on a unified way, providing a + simple interface for all of your infrastructure (multiple public + cloud providers, OpenStack based public/private clouds, Docker + servers, bare metal servers and now KVM hypervisors). +`Ravada `__ + Ravada is an open source tool for managing Virtual Desktop + Infrastructure (VDI). It is very easy to install and use. Following + the documentation, you'll be ready to deploy virtual machines in + minutes. The only requirements for the users are a Web browser and a + lightweight remote viewer. +`Virtlyst `__ + Virtlyst is an open source web application built with C++11, Cutelyst + and Qt. It features: + + - Low memory usage (around 5 MiB of RAM) + - Look and feel easily customized with HTML templates that use the + Django syntax + - VNC/Spice console directly in the browser using websockets on the + same HTTP port + - Host and Domain statistics graphs (CPU, Memory, IO, Network) + - Connect to multiple libvirtd instances (over local Unix domain + socket, SSH, TCP and TLS) + - Manage Storage Pools, Storage Volumes, Networks, Interfaces, and + Secrets + - Create and launch VMs + - Configure VMs with easy panels or go pro and edit the VM's XML + +Other +----- + +`Cuckoo Sandbox `__ + Cuckoo Sandbox is a malware analysis system. You can throw any + suspicious file at it and in a matter of seconds Cuckoo will provide + you back some detailed results outlining what such file did when + executed inside an isolated environment. And libvirt is one of the + backends that can be used for the isolated environment. + +.. |libvirt powered 96| image:: logos/logo-square-powered-96.png +.. |libvirt powered 128| image:: logos/logo-square-powered-128.png +.. |libvirt powered 192| image:: logos/logo-square-powered-192.png +.. |libvirt powered 256| image:: logos/logo-square-powered-256.png diff --git a/docs/meson.build b/docs/meson.build index 942cce6fdc..b61377ea8b 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'apps', 'architecture', 'auditlog', 'auth', @@ -107,6 +106,7 @@ docs_rst_files =3D [ 'advanced-tests', 'api_extension', 'api', + 'apps', 'best-practices', 'ci', 'coding-style', --=20 2.29.2 From nobody Sun May 5 18:42:52 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.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 216.205.24.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=1615549512; cv=none; d=zohomail.com; s=zohoarc; b=e+CxLC3FyB3wH939Gt2Unp/RnEiKRvjW1rcyjk5ilKY8WvFvladre3kuaBUDbajvN93FbduudqZQ0RD1PZnclQThHo/3ed3xHcpFMrTEafc5OdRejA7O8g6M8ec7QL3ZtzqfWCETbhGYCSuqS5rYNSC77BCdGjhAx3+nvLR/JAU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549512; h=Content-Type:Content-Transfer-Encoding:Cc: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=yfOkgjfPU3yfSJ2iTppR4YrtcGfvHOto/y/JpXYtNvY=; b=E5lLG/ApX5aYzFMZBAE7uts6JEcsINxcjT1l5V0POWBUUfHTGuc4CNXQD6A3Y/T2jfJb3bcI7IplDLQeWAsJI2kejyZNrRGHmBHOpzz+bAQ5xy61TFzfL/aZhQ/8La11eoF87cQ40tWgRnNMgFkCuurT9dBIxJmQEkQM3nhej8U= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1615549512754182.7388161172571; Fri, 12 Mar 2021 03:45:12 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-381-fqlGEBAkMg6QcjQ3z4uNMQ-1; Fri, 12 Mar 2021 06:45:09 -0500 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E6A701084C99; Fri, 12 Mar 2021 11:45:02 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B8A1260C03; Fri, 12 Mar 2021 11:45:02 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 7136A57DC8; Fri, 12 Mar 2021 11:45:02 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhMXo024873 for ; Fri, 12 Mar 2021 06:43:22 -0500 Received: by smtp.corp.redhat.com (Postfix) id 1522919813; Fri, 12 Mar 2021 11:43:22 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6145350EDF; Fri, 12 Mar 2021 11:43:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549511; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=yfOkgjfPU3yfSJ2iTppR4YrtcGfvHOto/y/JpXYtNvY=; b=CUU9H5wH5Yag6/AN6qEEGH57NCAjh0zJoTjb8Y6a8yaBTGDZft5T1a/Wt1Ne8NM1EG2bT8 UXbf3TeSbs/Dm6Do2I7ddlGhu0pq/1CHyn+qWlgOo07ob55XS2VPOkEfZExjoZ46sxjLTy fK33HuKjgsnuJ4TV0u/azun1Tt4PGA8= X-MC-Unique: fqlGEBAkMg6QcjQ3z4uNMQ-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 5/9] docs: html.in: Convert architecture to rst Date: Fri, 12 Mar 2021 12:43:08 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 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) Content-Type: text/plain; charset="utf-8" Signed-off-by: Erik Skultety --- docs/architecture.html.in | 82 -------------------------------------- docs/architecture.rst | 83 +++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 84 insertions(+), 83 deletions(-) delete mode 100644 docs/architecture.html.in create mode 100644 docs/architecture.rst diff --git a/docs/architecture.html.in b/docs/architecture.html.in deleted file mode 100644 index 7a5cf2dca8..0000000000 --- a/docs/architecture.html.in +++ /dev/null @@ -1,82 +0,0 @@ - - - - -

          libvirt architecture

          - -

          - Currently libvirt supports 2 kind of virtualization, and its - internal structure is based on a driver model which simplifies - adding new - engines: -

          - -
            - -

            Xen support

            - -

            When running in a Xen environment, programs using libvirt have to e= xecute -in "Domain 0", which is the primary Linux OS loaded on the machine. That OS -kernel provides most if not all of the actual drivers used by the set of -domains. It also runs the Xen Store, a database of information shared by t= he -hypervisor, the backend drivers, any running domains, and libxl (aka libxe= nlight). -libxl provides a set of APIs for creating and managing domains, which can = be used -by applications such as the xl tool provided by Xen or libvirt. The hyperv= isor, -drivers, kernels and daemons communicate though a shared system bus -implemented in the hypervisor. The figure below tries to provide a view of -this environment:

            - 3D"The -

            The library will interact with libxl for all management operations -on a Xen system.

            -

            Note that the libvirt libxl driver only supports root access.

            - -

            QEMU and KVM support

            - -

            The model for QEMU and KVM is completely similar, basically KVM is = based -on QEMU for the process controlling a new domain, only small details diffe= rs -between the two. In both case the libvirt API is provided by a controlling -process forked by libvirt in the background and which launch and control t= he -QEMU or KVM process. That program called libvirt_qemud talks though a spec= ific -protocol to the library, and connects to the console of the QEMU process in -order to control and report on its status. Libvirt tries to expose all the -emulations models of QEMU, the selection is done when creating the new -domain, by specifying the architecture and machine type targeted.

            -

            The code controlling the QEMU process is available in the -qemud/ directory.

            - -

            Driver based architecture

            - -

            As the previous section explains, libvirt can communicate using dif= ferent -channels with the current hypervisor, and should also be able to use -different kind of hypervisor. To simplify the internal design, code, ease -maintenance and simplify the support of other virtualization engine the -internals have been structured as one core component, the libvirt.c module -acting as a front-end for the library API and a set of hypervisor drivers -defining a common set of routines. That way the Xen Daemon access, the Xen -Store one, the Hypervisor hypercall are all isolated in separate C modules -implementing at least a subset of the common operations defined by the -drivers present in driver.h:

            -
              -
            • xend_internal: implements the driver functions though the Xen - Daemon
              • -
            • xs_internal: implements the subset of the driver available thoug= h the - Xen Store
              • -
            • xen_internal: provide the implementation of the functions possib= le via - direct hypervisor access
              • -
            • proxy_internal: provide read-only Xen access via a proxy, the pr= oxy code - is in the proxy/ directory.
              • -
            • xm_internal: provide support for Xen defined but not running - domains.
              • -
            • qemu_internal: implement the driver functions for QEMU and - KVM virtualization engines. It also uses a qemud/ specific daemon - which interacts with the QEMU process to implement libvirt API.
              • -
            • test: this is a test driver useful for regression tests of the - front-end part of libvirt.
              • -
            -

            Note that a given driver may only implement a subset of those funct= ions, -(for example saving a Xen domain state to disk and restoring it is only -possible though the Xen Daemon), in that case the driver entry points for -unsupported functions are initialized to NULL.

            -

            - - diff --git a/docs/architecture.rst b/docs/architecture.rst new file mode 100644 index 0000000000..f74906d36e --- /dev/null +++ b/docs/architecture.rst @@ -0,0 +1,83 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +libvirt architecture +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Currently libvirt supports 2 kind of virtualization, and its internal +structure is based on a driver model which simplifies adding new +engines: + +.. contents:: + +Xen support +----------- + +When running in a Xen environment, programs using libvirt have to +execute in "Domain 0", which is the primary Linux OS loaded on the +machine. That OS kernel provides most if not all of the actual drivers +used by the set of domains. It also runs the Xen Store, a database of +information shared by the hypervisor, the backend drivers, any running +domains, and libxl (aka libxenlight). libxl provides a set of APIs for +creating and managing domains, which can be used by applications such as +the xl tool provided by Xen or libvirt. The hypervisor, drivers, kernels +and daemons communicate though a shared system bus implemented in the +hypervisor. The figure below tries to provide a view of this +environment: + +|The Xen architecture| + +The library will interact with libxl for all management operations on a +Xen system. + +Note that the libvirt libxl driver only supports root access. + +QEMU and KVM support +-------------------- + +The model for QEMU and KVM is completely similar, basically KVM is based +on QEMU for the process controlling a new domain, only small details +differs between the two. In both case the libvirt API is provided by a +controlling process forked by libvirt in the background and which launch +and control the QEMU or KVM process. That program called libvirt_qemud +talks though a specific protocol to the library, and connects to the +console of the QEMU process in order to control and report on its +status. Libvirt tries to expose all the emulations models of QEMU, the +selection is done when creating the new domain, by specifying the +architecture and machine type targeted. + +The code controlling the QEMU process is available in the ``qemud/`` +directory. + +Driver based architecture +------------------------- + +As the previous section explains, libvirt can communicate using +different channels with the current hypervisor, and should also be able +to use different kind of hypervisor. To simplify the internal design, +code, ease maintenance and simplify the support of other virtualization +engine the internals have been structured as one core component, the +libvirt.c module acting as a front-end for the library API and a set of +hypervisor drivers defining a common set of routines. That way the Xen +Daemon access, the Xen Store one, the Hypervisor hypercall are all +isolated in separate C modules implementing at least a subset of the +common operations defined by the drivers present in driver.h: + +- xend_internal: implements the driver functions though the Xen Daemon +- xs_internal: implements the subset of the driver available though the + Xen Store +- xen_internal: provide the implementation of the functions possible + via direct hypervisor access +- proxy_internal: provide read-only Xen access via a proxy, the proxy + code is in the ``proxy/`` directory. +- xm_internal: provide support for Xen defined but not running domains. +- qemu_internal: implement the driver functions for QEMU and KVM + virtualization engines. It also uses a qemud/ specific daemon which + interacts with the QEMU process to implement libvirt API. +- test: this is a test driver useful for regression tests of the + front-end part of libvirt. + +Note that a given driver may only implement a subset of those functions, +(for example saving a Xen domain state to disk and restoring it is only +possible though the Xen Daemon), in that case the driver entry points +for unsupported functions are initialized to NULL. + +.. |The Xen architecture| image:: architecture.gif diff --git a/docs/meson.build b/docs/meson.build index b61377ea8b..0e0c266cb9 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'architecture', 'auditlog', 'auth', 'bindings', @@ -107,6 +106,7 @@ docs_rst_files =3D [ 'api_extension', 'api', 'apps', + 'architecture', 'best-practices', 'ci', 'coding-style', --=20 2.29.2 From nobody Sun May 5 18:42:52 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.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 216.205.24.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=1615549521; cv=none; d=zohomail.com; s=zohoarc; b=ULezgDyClpxpimm61Mi0WzcxcEvXe6D3RMR4GIM8OziW1MgTxoKzYdsrOTICgfAysMZRe0SRPMfj+ygwyTmdf3+nvPdwaQPBOJhQtKNxcldr9FX0U/ANXmiyhGQq+xswySkspXHerlcifqkf8KPtniB4oFY27yYd20jWq0ucQDA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549521; h=Content-Type:Content-Transfer-Encoding:Cc: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=UJCwcLlYE2R62U62eAKIyB8wlF45cXJo9yWbbHMlRrw=; b=S8YtNAIp1QE0LXL1YrGMjwoH372rvKYuDXwz0gkGkfk61TR7h/2zSG8p8mEdhtduu1YwL4gUWVIRrR5uAYg4c+a9bM2WZXzN0lkB7Oo7QFaAu9q7Jc9kKw3z98r2/JpyG7zRYUyeFzaY736ymf2IoJDFgL/RHn/xiFOBuzOWa1M= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1615549521504903.2912419395309; Fri, 12 Mar 2021 03:45:21 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-137-7BCqr-i0NxSY51BHoMsgiQ-1; Fri, 12 Mar 2021 06:45:14 -0500 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 18FBBDF8A3; Fri, 12 Mar 2021 11:45:07 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D1BE117D61; Fri, 12 Mar 2021 11:45:06 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 3F7E057DCB; Fri, 12 Mar 2021 11:45:06 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhN26024890 for ; Fri, 12 Mar 2021 06:43:23 -0500 Received: by smtp.corp.redhat.com (Postfix) id 13D9F60657; Fri, 12 Mar 2021 11:43:23 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6380860636; Fri, 12 Mar 2021 11:43:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549520; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=UJCwcLlYE2R62U62eAKIyB8wlF45cXJo9yWbbHMlRrw=; b=GTL+OFEUiOyr1E8lPAqhXpJPQoWIfuWlQ8IF5yy04cddWoQis1RXhpeqKGelnsbIwegKI1 73FnP60UZkfTQIUrUM7I8JjhmDWJDmWkv0eMeHMnvfRJuQMv16sIBgf23/jzBk346gtsqs LzAQNJSOgvx86YOdxqu4CQZu3xW2AZM= X-MC-Unique: 7BCqr-i0NxSY51BHoMsgiQ-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 6/9] docs: html.in: Convert auditlog to rst Date: Fri, 12 Mar 2021 12:43:09 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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) Content-Type: text/plain; charset="utf-8" Signed-off-by: Erik Skultety Reviewed-by: Peter Krempa --- docs/auditlog.html.in | 375 ------------------------------------------ docs/auditlog.rst | 321 ++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 322 insertions(+), 376 deletions(-) delete mode 100644 docs/auditlog.html.in create mode 100644 docs/auditlog.rst diff --git a/docs/auditlog.html.in b/docs/auditlog.html.in deleted file mode 100644 index eb00d9742e..0000000000 --- a/docs/auditlog.html.in +++ /dev/null @@ -1,375 +0,0 @@ - - - - -

            Audit log

            - -
              - -

              Introduction

              - -

              - A number of the libvirt virtualization drivers (QEMU/KVM and LXC) in= clude - support for logging details of important operations to the host's au= dit - subsystem. This provides administrators / auditors with a canonical = historical - record of changes to virtual machines' / containers' lifecycle state= s and - their configuration. On hosts which are running the Linux audit daem= on, - the logs will usually end up in /var/log/audit/audit.log -

              - -

              Configuration

              - -

              - The libvirt audit integration is enabled by default on any host whic= h has - the Linux audit subsystem active, and disabled otherwise. It is poss= ible - to alter this behaviour in the /etc/libvirt/libvirtd.conf - configuration file, via the audit_level parameter -

              - -
                -
              • audit_level=3D0 - libvirt auditing is disabled rega= rdless - of host audit subsystem enablement.
                • -
              • audit_level=3D1 - libvirt auditing is enabled if th= e host - audit subsystem is enabled, otherwise it is disabled. This is the - default behaviour.
                • -
              • audit_level=3D2 - libvirt auditing is enabled regar= dless - of host audit subsystem enablement. If the host audit subsystem is - disabled, then libvirtd will refuse to complete startup and exit w= ith - an error.
                • -
              - -

              - In addition to have formal messages sent to the audit subsystem it is - possible to tell libvirt to inject messages into its own logging - layer. This will result in messages ending up in the systemd journal - or /var/log/libvirt/libvirtd.log on non-systemd hosts. - This is disabled by default, but can be requested by setting the - audit_logging=3D1 configuration parameter in the same f= ile - mentioned above. -

              - -

              Message types

              - -

              - Libvirt defines three core audit message types each of which will - be described below. There are a number of common fields that will - be reported for all message types. -

              - -
              -
              pid
              -
              Process ID of the libvirtd daemon generating the audit record. -
              uid
              -
              User ID of the libvirtd daemon process generating the audit reco= rd.
              -
              subj
              -
              Security context of the libvirtd daemon process generating the a= udit record.
              -
              msg
              -
              String containing a list of key=3Dvalue pairs specific to the ty= pe of audit record being reported.
              -
              - -

              - Some fields in the msg string are common to audit recor= ds -

              - -
              -
              virt
              -
              Type of virtualization driver used. One of qemu or = lxc
              -
              vm
              -
              Host driver unique name of the guest
              -
              uuid
              -
              Globally unique identifier for the guest
              -
              exe
              -
              Path of the libvirtd daemon
              -
              hostname
              -
              Currently unused
              -
              addr
              -
              Currently unused
              -
              terminal
              -
              Currently unused
              -
              res
              -
              Result of the action, either success or faile= d
              -
              - -

              VIRT_CONTROL

              - -

              - Reports change in the lifecycle state of a virtual machine. The msg - field will include the following sub-fields -

              - -
              -
              op
              -
              Type of operation performed. One of start, st= op or init
              -
              reason
              -
              The reason which caused the operation to happen
              -
              vm-pid
              -
              ID of the primary/leading process associated with the guest
              -
              init-pid
              -
              ID of the init process in a container. Only if op=3Dinit and virt=3Dlxc
              -
              pid-ns
              -
              Namespace ID of the init process in a container. On= ly if op=3Dinit and virt=3Dlxc
              -
              - -

              VIRT_MACHINE_ID

              - -

              - Reports the association of a security context with a guest. The msg - field will include the following sub-fields -

              - -
              -
              model
              -
              The security driver type. One of selinux or a= pparmor
              -
              vm-ctx
              -
              Security context for the guest process
              -
              img-ctx
              -
              Security context for the guest disk images and other assigned ho= st resources
              -
              - -

              VIRT_RESOURCE

              - -

              - Reports the usage of a host resource by a guest. The fields include = will - vary according to the type of device being reported. When the guest = is - initially booted records will be generated for all assigned resource= s. - If any changes are made to the running guest configuration, for exam= ple - hotplug devices, or adjust resources allocation, further records will - be generated. -

              - -

              Virtual CPU

              - -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to vcpu
              -
              old-vcpu
              -
              Original vCPU count, or 0
              -
              new-vcpu
              -
              Updated vCPU count
              -
              - - -

              Memory

              - -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to mem
              -
              old-mem
              -
              Original memory size in bytes, or 0
              -
              new-mem
              -
              Updated memory size in bytes
              -
              - -

              Disk

              -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to disk
              -
              old-disk
              -
              Original host file or device path acting as the disk backing fil= e
              -
              new-disk
              -
              Updated host file or device path acting as the disk backing file=
              -
              - -

              Network interface

              - -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to net
              -
              old-net
              -
              Original MAC address of the guest network interface
              -
              new-net
              -
              Updated MAC address of the guest network interface
              -
              - -

              - If there is a host network interface associated with the guest NIC t= hen - further records may be generated -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to net
              -
              net
              -
              MAC address of the host network interface
              -
              rdev
              -
              Name of the host network interface
              -
              - -

              Filesystem

              -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to fs
              -
              old-fs
              -
              Original host directory, file or device path backing the filesys= tem
              -
              new-fs
              -
              Updated host directory, file or device path backing the filesyst= em
              -
              - -

              Host device

              -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to hostdev or dev
              -
              dev
              -
              The unique bus identifier of the USB, PCI or SCSI device, if resrc=3Ddev
              -
              disk
              -
              The path of the block device assigned to the guest, if res= rc=3Dhostdev
              -
              chardev
              -
              The path of the character device assigned to the guest, if resrc=3Dhostdev
              -
              - -

              TPM

              -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to tpm or = tpm-emulator
              -
              device
              -
              The path of the host TPM device assigned to the guest
              -
              - -

              RNG

              -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to rng
              -
              old-rng
              -
              Original path of the host entropy source for the RNG
              -
              new-rng
              -
              Updated path of the host entropy source for the RNG
              -
              - -

              console/serial/parallel/channel<= /h4> -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to chardev
              -
              old-chardev
              -
              Original path of the backing character device for given emulated= device
              -
              new-chardev
              -
              Updated path of the backing character device for given emulated = device
              -
              - -

              smartcard

              -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to smartcard
              -
              old-smartcard
              -
              Original path of the backing character device, certificate store= or - "nss-smartcard-device" for host smartcard passthrough. -
              -
              new-smartcard
              -
              Updated path of the backing character device, certificate store = or - "nss-smartcard-device" for host smartcard passthrough. -
              -
              - -

              Redirected device

              -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to redir
              -
              bus
              -
              The bus type, only usb allowed
              -
              device
              -
              The device type, only USB redir allowed
              -
              - -

              Control group

              - -

              - The msg field will include the following sub-fields -

              - -
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              resrc
              -
              The type of resource assigned. Set to cgroup
              -
              cgroup
              -
              The name of the cgroup controller
              -
              - - -

              Shared memory

              -

              - The msg field will include the following sub-fields -

              - -
              -
              resrc
              -
              The type of resource assigned. Set to shmem
              -
              reason
              -
              The reason which caused the resource to be assigned to happen -
              size
              -
              The size of the shared memory region
              -
              shmem
              -
              Name of the shared memory region
              -
              source
              -
              Path of the backing character device for given emulated device -
              - - - diff --git a/docs/auditlog.rst b/docs/auditlog.rst new file mode 100644 index 0000000000..e99374ffa8 --- /dev/null +++ b/docs/auditlog.rst @@ -0,0 +1,321 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D +Audit log +=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Introduction +------------ + +A number of the libvirt virtualization drivers (QEMU/KVM and LXC) +include support for logging details of important operations to the +host's audit subsystem. This provides administrators / auditors with a +canonical historical record of changes to virtual machines' / +containers' lifecycle states and their configuration. On hosts which are +running the Linux audit daemon, the logs will usually end up in +``/var/log/audit/audit.log`` + +Configuration +------------- + +The libvirt audit integration is enabled by default on any host which +has the Linux audit subsystem active, and disabled otherwise. It is +possible to alter this behaviour in the ``/etc/libvirt/libvirtd.conf`` +configuration file, via the ``audit_level`` parameter + +- ``audit_level=3D0`` - libvirt auditing is disabled regardless of host + audit subsystem enablement. +- ``audit_level=3D1`` - libvirt auditing is enabled if the host audit + subsystem is enabled, otherwise it is disabled. This is the default + behaviour. +- ``audit_level=3D2`` - libvirt auditing is enabled regardless of host + audit subsystem enablement. If the host audit subsystem is disabled, + then libvirtd will refuse to complete startup and exit with an error. + +In addition to have formal messages sent to the audit subsystem it is +possible to tell libvirt to inject messages into its own logging layer. +This will result in messages ending up in the systemd journal or +``/var/log/libvirt/libvirtd.log`` on non-systemd hosts. This is disabled +by default, but can be requested by setting the ``audit_logging=3D1`` +configuration parameter in the same file mentioned above. + +Message types +------------- + +Libvirt defines three core audit message types each of which will be +described below. There are a number of common fields that will be +reported for all message types. + +``pid`` + Process ID of the libvirtd daemon generating the audit record. +``uid`` + User ID of the libvirtd daemon process generating the audit record. +``subj`` + Security context of the libvirtd daemon process generating the audit + record. +``msg`` + String containing a list of key=3Dvalue pairs specific to the type of + audit record being reported. + +Some fields in the ``msg`` string are common to audit records + +``virt`` + Type of virtualization driver used. One of ``qemu`` or ``lxc`` +``vm`` + Host driver unique name of the guest +``uuid`` + Globally unique identifier for the guest +``exe`` + Path of the libvirtd daemon +``hostname`` + Currently unused +``addr`` + Currently unused +``terminal`` + Currently unused +``res`` + Result of the action, either ``success`` or ``failed`` + +VIRT_CONTROL +~~~~~~~~~~~~ + +Reports change in the lifecycle state of a virtual machine. The ``msg`` +field will include the following sub-fields + +``op`` + Type of operation performed. One of ``start``, ``stop`` or ``init`` +``reason`` + The reason which caused the operation to happen +``vm-pid`` + ID of the primary/leading process associated with the guest +``init-pid`` + ID of the ``init`` process in a container. Only if ``op=3Dinit`` and + ``virt=3Dlxc`` +``pid-ns`` + Namespace ID of the ``init`` process in a container. Only if + ``op=3Dinit`` and ``virt=3Dlxc`` + +VIRT_MACHINE_ID +~~~~~~~~~~~~~~~ + +Reports the association of a security context with a guest. The ``msg`` +field will include the following sub-fields + +``model`` + The security driver type. One of ``selinux`` or ``apparmor`` +``vm-ctx`` + Security context for the guest process +``img-ctx`` + Security context for the guest disk images and other assigned host + resources + +VIRT_RESOURCE +~~~~~~~~~~~~~ + +Reports the usage of a host resource by a guest. The fields include will +vary according to the type of device being reported. When the guest is +initially booted records will be generated for all assigned resources. +If any changes are made to the running guest configuration, for example +hotplug devices, or adjust resources allocation, further records will be +generated. + +Virtual CPU +^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``vcpu`` +``old-vcpu`` + Original vCPU count, or 0 +``new-vcpu`` + Updated vCPU count + +Memory +^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``mem`` +``old-mem`` + Original memory size in bytes, or 0 +``new-mem`` + Updated memory size in bytes + +Disk +^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``disk`` +``old-disk`` + Original host file or device path acting as the disk backing file +``new-disk`` + Updated host file or device path acting as the disk backing file + +Network interface +^^^^^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``net`` +``old-net`` + Original MAC address of the guest network interface +``new-net`` + Updated MAC address of the guest network interface + +If there is a host network interface associated with the guest NIC then +further records may be generated + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``net`` +``net`` + MAC address of the host network interface +``rdev`` + Name of the host network interface + +Filesystem +^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``fs`` +``old-fs`` + Original host directory, file or device path backing the filesystem +``new-fs`` + Updated host directory, file or device path backing the filesystem + +Host device +^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``hostdev`` or ``dev`` +``dev`` + The unique bus identifier of the USB, PCI or SCSI device, if + ``resrc=3Ddev`` +``disk`` + The path of the block device assigned to the guest, if + ``resrc=3Dhostdev`` +``chardev`` + The path of the character device assigned to the guest, if + ``resrc=3Dhostdev`` + +TPM +^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``tpm`` or ``tpm-emulator`` +``device`` + The path of the host TPM device assigned to the guest + +RNG +^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``rng`` +``old-rng`` + Original path of the host entropy source for the RNG +``new-rng`` + Updated path of the host entropy source for the RNG + +console/serial/parallel/channel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``chardev`` +``old-chardev`` + Original path of the backing character device for given emulated + device +``new-chardev`` + Updated path of the backing character device for given emulated + device + +smartcard +^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``smartcard`` +``old-smartcard`` + Original path of the backing character device, certificate store or + "nss-smartcard-device" for host smartcard passthrough. +``new-smartcard`` + Updated path of the backing character device, certificate store or + "nss-smartcard-device" for host smartcard passthrough. + +Redirected device +^^^^^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``redir`` +``bus`` + The bus type, only ``usb`` allowed +``device`` + The device type, only ``USB redir`` allowed + +Control group +^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``reason`` + The reason which caused the resource to be assigned to happen +``resrc`` + The type of resource assigned. Set to ``cgroup`` +``cgroup`` + The name of the cgroup controller + +Shared memory +^^^^^^^^^^^^^ + +The ``msg`` field will include the following sub-fields + +``resrc`` + The type of resource assigned. Set to ``shmem`` +``reason`` + The reason which caused the resource to be assigned to happen +``size`` + The size of the shared memory region +``shmem`` + Name of the shared memory region +``source`` + Path of the backing character device for given emulated device diff --git a/docs/meson.build b/docs/meson.build index 0e0c266cb9..f80a08112e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'auditlog', 'auth', 'bindings', 'bugs', @@ -107,6 +106,7 @@ docs_rst_files =3D [ 'api', 'apps', 'architecture', + 'auditlog', 'best-practices', 'ci', 'coding-style', --=20 2.29.2 From nobody Sun May 5 18:42:52 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.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 63.128.21.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=1615549521; cv=none; d=zohomail.com; s=zohoarc; b=NusH/l1BgbM4+5wyECWWig7lTt+PIr5PnXgBmTLQPxwm8RnnBCJeAWZ+cUZv8XDKLI6UHJVsRMDlFQqdMJyO/Tg3IiEGPWYpHIcKwn9BPlTHCLSfxMI2BUeK1J2vGdUhDShblWe3ALZ+a9TFU5uhM4al7vSicKsSNiB8TUNXHZs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549521; h=Content-Type:Content-Transfer-Encoding:Cc: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=0+NkZF+hQXEUrXNUOALMzHegn/Wj0gBmO68Pc5dxlCI=; b=WJ95YnRONQeqC3ydw581yNkgtArvPkOM8VCke4Fi/aB3nbtrIE0Qxj4AZD8R9GsFyKIwPw+cN/DF366SP6mV1jvzMu0/GnVtelS8pVCxmWXVemI6iw9/OfEAef45grlNRvzEB9FyE5hpJNu9zmKGBC4AObXU1QxHOr2Q77XrvRQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1615549521873902.1889994541986; Fri, 12 Mar 2021 03:45:21 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-426-VFr8NskPMWGBe1joRRr_pA-1; Fri, 12 Mar 2021 06:45:17 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E24FD107ACCA; Fri, 12 Mar 2021 11:45:10 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B29AF59443; Fri, 12 Mar 2021 11:45:10 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 67B7F1800B99; Fri, 12 Mar 2021 11:45:10 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhOsT024898 for ; Fri, 12 Mar 2021 06:43:24 -0500 Received: by smtp.corp.redhat.com (Postfix) id 191D59CA0; Fri, 12 Mar 2021 11:43:24 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 66A2560636; Fri, 12 Mar 2021 11:43:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549520; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=0+NkZF+hQXEUrXNUOALMzHegn/Wj0gBmO68Pc5dxlCI=; b=EyMgqvNGriw6rtL+MJjFoBKXML5ncQFtgJp2SvmGqNrUfltAkEqwphDDDPjEsVh6WSbjKL wx+YFhX6WiG7yq+ohrl2bVNsZkSSmXpWZ1OgXmOLYfIOIes79ny174KShdHHi5NIS5yRfc PC33FpX2OC8PLm9AYKfS2AELM3Htrdw= X-MC-Unique: VFr8NskPMWGBe1joRRr_pA-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 7/9] docs: html.in: Convert auth to rst Date: Fri, 12 Mar 2021 12:43:10 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 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) Content-Type: text/plain; charset="utf-8" Signed-off-by: Erik Skultety --- docs/auth.html.in | 368 ---------------------------------------------- docs/auth.rst | 343 ++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 344 insertions(+), 369 deletions(-) delete mode 100644 docs/auth.html.in create mode 100644 docs/auth.rst diff --git a/docs/auth.html.in b/docs/auth.html.in deleted file mode 100644 index 9b940a8598..0000000000 --- a/docs/auth.html.in +++ /dev/null @@ -1,368 +0,0 @@ - - - - -

              Connection authentication

              -

              - When connecting to libvirt, some connections may require client - authentication before allowing use of the APIs. The set of possible - authentication mechanisms is administrator controlled, independent - of applications using libvirt. Once authenticated, libvirt can apply - fine grained access control to the operatio= ns - performed by a client. -

              - -
                - -

                Client configuration

                - -

                - When connecting to a remote hypervisor which requires authentication, -most libvirt applications will prompt the user for the credentials. It is -also possible to provide a client configuration file containing all the -authentication credentials, avoiding any interaction. Libvirt will look -for the authentication file using the following sequence: -

                -
                  -
                1. The file path specified by the $LIBVIRT_AUTH_FILE environment - variable.
                  2. -
                2. The file path specified by the "authfile=3D/some/file" URI - query parameter
                  3. -
                3. The file $XDG_CONFIG_HOME/libvirt/auth.conf
                  4. -
                4. The file /etc/libvirt/auth.conf
                  5. -
                - -

                - The auth configuration file uses the traditional ".ini" - style syntax. There are two types of groups that can be present in - the config. First there are one or more credential - sets, which provide the actual authentication credentials. The keys - within the group may be: -

                - -
                  -
                • username: the user login name to act as. This - is relevant for ESX, Xen, HyperV and SSH, but probably not - the one you want to libvirtd with SASL.
                  • -
                • authname: the name to authorize as. This is - what is commonly required for libvirtd with SASL.
                  • -
                • password: the secret password
                  • -
                • realm: the domain realm for SASL, mostly - unused
                  • -
                - -

                - Each set of credentials has a name, which is part of the group - entry name. Overall the syntax is -

                - - 
                -[credentials-$NAME]
-credname1=3Dvalue1
-credname2=3Dvalue2
                - -

                - For example, to define two sets of credentials used for production - and test machines, using libvirtd, and a further ESX server for dev: -

                -
                -[credentials-test]
-authname=3Dfred
-password=3D123456
-
-[credentials-prod]
-authname=3Dbar
-password=3Dletmein
-
-[credentials-dev]
-username=3Djoe
-password=3Dhello
-
-[credentials-defgrp]
-username=3Ddefuser
-password=3Ddefpw
                - -

                - The second set of groups provide mappings of credentials to - specific machine services. The config file group names compromise - the service type and host: -

                - - 
                -[auth-$SERVICE-$HOSTNAME]
-credentials=3D$CREDENTIALS
                - -

                - For example, following the previous example, here is how to - map some machines. For convenience libvirt supports a default - mapping of credentials to machines: -

                - - 
                -[auth-libvirt-test1.example.com]
-credentials=3Dtest
-
-[auth-libvirt-test2.example.com]
-credentials=3Dtest
-
-[auth-libvirt-demo3.example.com]
-credentials=3Dtest
-
-[auth-libvirt-prod1.example.com]
-credentials=3Dprod
-
-[auth-libvirt-default]
-credentials=3Ddefgrp
-
-[auth-esx-dev1.example.com]
-credentials=3Ddev
-
-[auth-esx-default]
-credentials=3Ddefgrp
                - - -

                - The following service types are known to libvirt: -

                - -
                  -
                • esx - used for connections to an ESX or - VirtualCenter server
                  • -
                • hyperv - used for connections to an HyperV - server
                  • -
                • libvirt - used for connections to a libvirtd - server, which is configured with SASL auth
                  • -
                • ssh - used for connections to a remote QEMU driver - over SSH
                  • -
                - -

                - Applications using libvirt are free to use this same configuration - file for storing other credentials. For example, it can be used - to storage VNC or SPICE login credentials -

                - -

                Server configuration

                -

                -The libvirt daemon allows the administrator to choose the authentication -mechanisms used for client connections on each network socket independentl= y. -This is primarily controlled via the libvirt daemon master config file in -/etc/libvirt/libvirtd.conf. Each of the libvirt sockets can -have its authentication mechanism configured independently. There is -currently a choice of none, polkit, and sa= sl. -The SASL scheme can be further configured to choose between a large -number of different mechanisms. -

                -

                UNIX socket permissions/group<= /h2> -

                -If libvirt does not contain support for PolicyKit, then access control for -the UNIX domain socket is done using traditional file user/group ownership -and permissions. There are 2 sockets, one for full read-write access, the -other for read-only access. The RW socket will be restricted (mode 0700) to -only allow the root user to connect. The read-only socket will -be open access (mode 0777) to allow any user to connect. -

                -

                -To allow non-root users greater access, the libvirtd.conf file -can be edited to change the permissions via the unix_sock_rw_perms, -config parameter and to set a user group via the unix_sock_group -parameter. For example, setting the former to mode 0770 and t= he -latter wheel would let any user in the wheel group connect to -the libvirt daemon. -

                -

                UNIX socket PolicyKit auth

                -

                -If libvirt contains support for PolicyKit, then access control options are -more advanced. The auth_unix_rw parameter will default to -polkit, and the file permissions will default to 0777 -even on the RW socket. Upon connecting to the socket, the client applicati= on -will be required to identify itself with PolicyKit. The default policy for= the -RW daemon socket will require any application running in the current deskt= op -session to authenticate using the user's password. This is akin to s= udo -auth, but does not require that the client application ultimately run as r= oot. -Default policy will still allow any application to connect to the RO socke= t. -

                -

                -The default policy can be overridden by creating a new policy file in the -/etc/polkit-1/rules.d directory. Information on the options -available can be found by reading the polkit(8) man page. The -two libvirt actions are named org.libvirt.unix.manage for full -management access, and org.libvirt.unix.monitor for read-only -access. -

                -

                -As an example, creating /etc/polkit-1/rules.d/80-libvirt-manage.rule= s -with the following gives the user fred full management access -when accessing from an active local session: -

                -
                polkit.addRule(function(action, subject) {
-  if (action.id =3D=3D "org.libvirt.unix.manage" &&
-      subject.local && subject.active && subject.user =3D=
=3D "fred") {
-      return polkit.Result.YES;
-  }
-});
                -

                -Older versions of PolicyKit used policy files ending with .pkla in the -local override directory /etc/polkit-1/localauthority/50-local.d/. -Compatibility with this older format is provided by polkit-pkla-compat. As an -example, this gives the user fred full management access: -

                -
                [Allow fred libvirt management permissions]
-Identity=3Dunix-user:fred
-Action=3Dorg.libvirt.unix.manage
-ResultAny=3Dyes
-ResultInactive=3Dyes
-ResultActive=3Dyes
                -

                SASL pluggable authentication

                - -

                -Libvirt integrates with the cyrus-sasl library to provide a pluggable auth= entication -system using the SASL protocol. SASL can be used in combination with libvi= rtd's TLS -or TCP socket listeners. When used with the TCP listener, the SASL mechani= sm is -rqeuired to provide session encryption in addition to authentication. Only= a very -few SASL mechanisms are able to do this, and of those that can do it, only= the -GSSAPI plugin is considered acceptably secure by modern standards: -

                - -
                -
                GSSAPI
                -
                This is the current default mechanism to use with libvir= td. - It uses the Kerberos v5 authentication protocol underneath, and as= suming - the Kerberos client/server are configured with modern ciphers (AES= ), - it provides strong session encryption capabilities.
                - -
                DIGEST-MD5
                -
                This was previously set as the default mechanism to use with lib= virtd. - It provides a simple username/password based authentication mechan= ism - that includes session encryption. - RFC 6331, howe= ver, - documents a number of serious security flaws with DIGEST-MD5 and a= s a - result marks it as OBSOLETE. Specific concerns are th= at - it is vulnerable to MITM attacks and the MD5 hash can be brute-for= ced - to reveal the password. A replacement is provided via the SCRAM me= chanism, - however, note that this does not provide encryption, so the SCRAM - mechanism can only be used on the libvirtd TLS listener. -
                - -
                PASSDSS-3DES-1
                -
                This provides a simple username/password based authentication - mechanism that includes session encryption. The current cyrus-sasl - implementation does not provide a way to validate the server's - public key identity, thus it is susceptible to a MITM attacker - impersonating the server. It is also not enabled in many OS - distros when building SASL libraries.
                - -
                KERBEROS_V4
                -
                This uses the obsolete Kerberos v4 protocol to provide both auth= entication - and session encryption. Kerberos v4 protocol has been obsolete sin= ce the - early 1990's and has known security vulnerabilities so this will n= ever be - used in practice.
                -
                - -

                - Other SASL mechanisms, not listed above, can only be used when the l= ibvirtd - TLS or UNIX socket listeners. -

                - -

                Username/password auth

                -

                -As noted above, the DIGEST-MD5 mechanism is considered obsolete and should -not be used anymore. To provide a simple username/password auth scheme on -the libvirt UNIX socket or TLS listeners, however, it is possible to use -the SCRAM mechanism. The auth_unix_ro, auth_unix_rw, -auth_tls config params in libvirt.conf can be us= ed -to turn on SASL auth in these listeners. -

                -

                -Since the libvirt SASL config file defaults to using GSSAPI (Kerberos), a -config change is required to enable plain password auth. This is done by -editing /etc/sasl2/libvirt.conf to set the mech_list -parameter to scram-sha-1. -

                -

                -Out of the box, no user accounts are defined, so no clients will be able t= o authenticate -on the TCP socket. Adding users and setting their passwords is done with t= he saslpasswd2 -command. When running this command it is important to tell it that the app= name is libvirt. -As an example, to add a user fred, run -

                - 
                -# saslpasswd2 -a libvirt fred
-Password: xxxxxx
-Again (for verification): xxxxxx
-
                -

                -To see a list of all accounts the sasldblistusers2 command ca= n be used. -This command expects to be given the path to the libvirt user database, wh= ich is kept -in /etc/libvirt/passwd.db -

                - 
                -# sasldblistusers2 -f /etc/libvirt/passwd.db
-fred@t60wlan.home.berrange.com: userPassword
-
                -

                -Finally, to disable a user's access, the saslpasswd2 command = can be used -again: -

                - 
                -# saslpasswd2 -a libvirt -d fred
-
                -

                GSSAPI/Kerberos auth

                -

                -The plain TCP listener of the libvirt daemon defaults to using SASL for au= thentication. -The libvirt SASL config also defaults to GSSAPI, so there is no need to ed= it the -SASL config when using GSSAPI. If the libvirtd TLS or UNIX listeners are u= sed, -then the Kerberos session encryption will be disabled since it is not requ= ired -in these scenarios - only the plain TCP listener needs encryption -

                -

                -Some operating systems do not install the SASL kerberos plugin by default.= It -may be necessary to install a sub-package such as cyrus-sasl-gssapi<= /code>. -To check whether the Kerberos plugin is installed run the pluginview= er -program and verify that gssapi is listed, e.g.: -

                - 
                -# pluginviewer
-...snip...
-Plugin "gssapiv2" [loaded],     API version: 4
-        SASL mechanism: GSSAPI, best SSF: 56
-        security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIA=
LS|MUTUAL_AUTH
-        features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
-
                -

                -Next it is necessary for the administrator of the Kerberos realm to -issue a principal for the libvirt server. There needs to be one -principal per host running the libvirt daemon. The principal should be -named libvirt/full.hostname@KERBEROS.REALM. This is -typically done by running the kadmin.local command on the -Kerberos server, though some Kerberos servers have alternate ways of -setting up service principals. Once created, the principal should be -exported to a keytab, copied to the host running the libvirt daemon -and placed in /etc/libvirt/krb5.tab -

                - 
                -# kadmin.local
-kadmin.local: add_principal libvirt/foo.example.com
-Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
-Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
-Principal "libvirt/foo.example.com@EXAMPLE.COM" created.
-
-kadmin.local:  ktadd -k /root/libvirt-foo-example.tab libvirt/foo.example.=
com@EXAMPLE.COM
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/=
libvirt-foo-example.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-e=
xample.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-exam=
ple.tab.
-Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encry=
ption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-f=
oo-example.tab.
-
-kadmin.local: quit
-
-# scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5=
.tab
-# rm /root/libvirt-foo-example.tab
-
                -

                -Any client application wishing to connect to a Kerberos enabled libvirt se= rver -merely needs to run kinit to gain a user principal. This may = well -be done automatically when a user logs into a desktop session, if PAM is s= et up -to authenticate against Kerberos. -

                - - diff --git a/docs/auth.rst b/docs/auth.rst new file mode 100644 index 0000000000..26fa6c950c --- /dev/null +++ b/docs/auth.rst @@ -0,0 +1,343 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D +Connection authentication +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +When connecting to libvirt, some connections may require client +authentication before allowing use of the APIs. The set of possible +authentication mechanisms is administrator controlled, independent of +applications using libvirt. Once authenticated, libvirt can apply fine +grained `access control `__ to the operations performed by a +client. + +.. contents:: + +Client configuration +-------------------- + +When connecting to a remote hypervisor which requires authentication, +most libvirt applications will prompt the user for the credentials. It +is also possible to provide a client configuration file containing all +the authentication credentials, avoiding any interaction. Libvirt will +look for the authentication file using the following sequence: + +#. The file path specified by the $LIBVIRT_AUTH_FILE environment + variable. +#. The file path specified by the "authfile=3D/some/file" URI query + parameter +#. The file $XDG_CONFIG_HOME/libvirt/auth.conf +#. The file /etc/libvirt/auth.conf + +The auth configuration file uses the traditional ``".ini"`` style +syntax. There are two types of groups that can be present in the config. +First there are one or more **credential** sets, which provide the +actual authentication credentials. The keys within the group may be: + +- ``username``: the user login name to act as. This is relevant for + ESX, Xen, HyperV and SSH, but probably not the one you want to + libvirtd with SASL. +- ``authname``: the name to authorize as. This is what is commonly + required for libvirtd with SASL. +- ``password``: the secret password +- ``realm``: the domain realm for SASL, mostly unused + +Each set of credentials has a name, which is part of the group entry +name. Overall the syntax is + +:: + + [credentials-$NAME] + credname1=3Dvalue1 + credname2=3Dvalue2 + +For example, to define two sets of credentials used for production and +test machines, using libvirtd, and a further ESX server for dev: + +:: + + [credentials-test] + authname=3Dfred + password=3D123456 + + [credentials-prod] + authname=3Dbar + password=3Dletmein + + [credentials-dev] + username=3Djoe + password=3Dhello + + [credentials-defgrp] + username=3Ddefuser + password=3Ddefpw + +The second set of groups provide mappings of credentials to specific +machine services. The config file group names compromise the service +type and host: + +:: + + [auth-$SERVICE-$HOSTNAME] + credentials=3D$CREDENTIALS + +For example, following the previous example, here is how to map some +machines. For convenience libvirt supports a default mapping of +credentials to machines: + +:: + + [auth-libvirt-test1.example.com] + credentials=3Dtest + + [auth-libvirt-test2.example.com] + credentials=3Dtest + + [auth-libvirt-demo3.example.com] + credentials=3Dtest + + [auth-libvirt-prod1.example.com] + credentials=3Dprod + + [auth-libvirt-default] + credentials=3Ddefgrp + + [auth-esx-dev1.example.com] + credentials=3Ddev + + [auth-esx-default] + credentials=3Ddefgrp + +The following service types are known to libvirt: + +- ``esx`` - used for connections to an ESX or VirtualCenter server +- ``hyperv`` - used for connections to an HyperV server +- ``libvirt`` - used for connections to a libvirtd server, which is + configured with SASL auth +- ``ssh`` - used for connections to a remote QEMU driver over SSH + +Applications using libvirt are free to use this same configuration file +for storing other credentials. For example, it can be used to storage +VNC or SPICE login credentials + +Server configuration +-------------------- + +The libvirt daemon allows the administrator to choose the authentication +mechanisms used for client connections on each network socket +independently. This is primarily controlled via the libvirt daemon +master config file in ``/etc/libvirt/libvirtd.conf``. Each of the +libvirt sockets can have its authentication mechanism configured +independently. There is currently a choice of ``none``, ``polkit``, and +``sasl``. The SASL scheme can be further configured to choose between a +large number of different mechanisms. + +UNIX socket permissions/group +----------------------------- + +If libvirt does not contain support for PolicyKit, then access control +for the UNIX domain socket is done using traditional file user/group +ownership and permissions. There are 2 sockets, one for full read-write +access, the other for read-only access. The RW socket will be restricted +(mode 0700) to only allow the ``root`` user to connect. The read-only +socket will be open access (mode 0777) to allow any user to connect. + +To allow non-root users greater access, the ``libvirtd.conf`` file can +be edited to change the permissions via the ``unix_sock_rw_perms``, +config parameter and to set a user group via the ``unix_sock_group`` +parameter. For example, setting the former to mode ``0770`` and the +latter ``wheel`` would let any user in the wheel group connect to the +libvirt daemon. + +UNIX socket PolicyKit auth +-------------------------- + +If libvirt contains support for PolicyKit, then access control options +are more advanced. The ``auth_unix_rw`` parameter will default to +``polkit``, and the file permissions will default to ``0777`` even on +the RW socket. Upon connecting to the socket, the client application +will be required to identify itself with PolicyKit. The default policy +for the RW daemon socket will require any application running in the +current desktop session to authenticate using the user's password. This +is akin to ``sudo`` auth, but does not require that the client +application ultimately run as root. Default policy will still allow any +application to connect to the RO socket. + +The default policy can be overridden by creating a new policy file in +the ``/etc/polkit-1/rules.d`` directory. Information on the options +available can be found by reading the ``polkit(8)`` man page. The two +libvirt actions are named ``org.libvirt.unix.manage`` for full +management access, and ``org.libvirt.unix.monitor`` for read-only +access. + +As an example, creating +``/etc/polkit-1/rules.d/80-libvirt-manage.rules`` with the following +gives the user ``fred`` full management access when accessing from an +active local session: + +:: + + polkit.addRule(function(action, subject) { + if (action.id =3D=3D "org.libvirt.unix.manage" && + subject.local && subject.active && subject.user =3D=3D "fred") { + return polkit.Result.YES; + } + }); + +Older versions of PolicyKit used policy files ending with .pkla in the +local override directory ``/etc/polkit-1/localauthority/50-local.d/``. +Compatibility with this older format is provided by +`polkit-pkla-compat `__. As an +example, this gives the user ``fred`` full management access: + +:: + + [Allow fred libvirt management permissions] + Identity=3Dunix-user:fred + Action=3Dorg.libvirt.unix.manage + ResultAny=3Dyes + ResultInactive=3Dyes + ResultActive=3Dyes + +SASL pluggable authentication +----------------------------- + +Libvirt integrates with the cyrus-sasl library to provide a pluggable +authentication system using the SASL protocol. SASL can be used in +combination with libvirtd's TLS or TCP socket listeners. When used with +the TCP listener, the SASL mechanism is rqeuired to provide session +encryption in addition to authentication. Only a very few SASL +mechanisms are able to do this, and of those that can do it, only the +GSSAPI plugin is considered acceptably secure by modern standards: + +GSSAPI + **This is the current default mechanism to use with libvirtd**. It + uses the Kerberos v5 authentication protocol underneath, and assuming + the Kerberos client/server are configured with modern ciphers (AES), + it provides strong session encryption capabilities. +DIGEST-MD5 + This was previously set as the default mechanism to use with + libvirtd. It provides a simple username/password based authentication + mechanism that includes session encryption. `RFC + 6331 `__, however, documents a + number of serious security flaws with DIGEST-MD5 and as a result + marks it as ``OBSOLETE``. Specific concerns are that it is vulnerable + to MITM attacks and the MD5 hash can be brute-forced to reveal the + password. A replacement is provided via the SCRAM mechanism, however, + note that this does not provide encryption, so the SCRAM mechanism + can only be used on the libvirtd TLS listener. +PASSDSS-3DES-1 + This provides a simple username/password based authentication + mechanism that includes session encryption. The current cyrus-sasl + implementation does not provide a way to validate the server's public + key identity, thus it is susceptible to a MITM attacker impersonating + the server. It is also not enabled in many OS distros when building + SASL libraries. +KERBEROS_V4 + This uses the obsolete Kerberos v4 protocol to provide both + authentication and session encryption. Kerberos v4 protocol has been + obsolete since the early 1990's and has known security + vulnerabilities so this will never be used in practice. + +Other SASL mechanisms, not listed above, can only be used when the +libvirtd TLS or UNIX socket listeners. + +Username/password auth +~~~~~~~~~~~~~~~~~~~~~~ + +As noted above, the DIGEST-MD5 mechanism is considered obsolete and +should not be used anymore. To provide a simple username/password auth +scheme on the libvirt UNIX socket or TLS listeners, however, it is +possible to use the SCRAM mechanism. The ``auth_unix_ro``, +``auth_unix_rw``, ``auth_tls`` config params in ``libvirt.conf`` can be +used to turn on SASL auth in these listeners. + +Since the libvirt SASL config file defaults to using GSSAPI (Kerberos), +a config change is required to enable plain password auth. This is done +by editing ``/etc/sasl2/libvirt.conf`` to set the ``mech_list`` +parameter to ``scram-sha-1``. + +Out of the box, no user accounts are defined, so no clients will be able +to authenticate on the TCP socket. Adding users and setting their +passwords is done with the ``saslpasswd2`` command. When running this +command it is important to tell it that the appname is ``libvirt``. As +an example, to add a user ``fred``, run + +:: + + # saslpasswd2 -a libvirt fred + Password: xxxxxx + Again (for verification): xxxxxx + +To see a list of all accounts the ``sasldblistusers2`` command can be +used. This command expects to be given the path to the libvirt user +database, which is kept in ``/etc/libvirt/passwd.db`` + +:: + + # sasldblistusers2 -f /etc/libvirt/passwd.db + fred@t60wlan.home.berrange.com: userPassword + +Finally, to disable a user's access, the ``saslpasswd2`` command can be +used again: + +:: + + # saslpasswd2 -a libvirt -d fred + +GSSAPI/Kerberos auth +~~~~~~~~~~~~~~~~~~~~ + +The plain TCP listener of the libvirt daemon defaults to using SASL for +authentication. The libvirt SASL config also defaults to GSSAPI, so +there is no need to edit the SASL config when using GSSAPI. If the +libvirtd TLS or UNIX listeners are used, then the Kerberos session +encryption will be disabled since it is not required in these scenarios +- only the plain TCP listener needs encryption + +Some operating systems do not install the SASL kerberos plugin by +default. It may be necessary to install a sub-package such as +``cyrus-sasl-gssapi``. To check whether the Kerberos plugin is installed +run the ``pluginviewer`` program and verify that ``gssapi`` is listed, +e.g.: + +:: + + # pluginviewer + ...snip... + Plugin "gssapiv2" [loaded], API version: 4 + SASL mechanism: GSSAPI, best SSF: 56 + security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDEN= TIALS|MUTUAL_AUTH + features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQ= DN + +Next it is necessary for the administrator of the Kerberos realm to +issue a principal for the libvirt server. There needs to be one +principal per host running the libvirt daemon. The principal should be +named ``libvirt/full.hostname@KERBEROS.REALM``. This is typically done +by running the ``kadmin.local`` command on the Kerberos server, though +some Kerberos servers have alternate ways of setting up service +principals. Once created, the principal should be exported to a keytab, +copied to the host running the libvirt daemon and placed in +``/etc/libvirt/krb5.tab`` + +:: + + # kadmin.local + kadmin.local: add_principal libvirt/foo.example.com + Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": + Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM": + Principal "libvirt/foo.example.com@EXAMPLE.COM" created. + + kadmin.local: ktadd -k /root/libvirt-foo-example.tab libvirt/foo.examp= le.com@EXAMPLE.COM + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/ro= ot/libvirt-foo-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-fo= o-example.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-e= xample.tab. + Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, en= cryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvir= t-foo-example.tab. + + kadmin.local: quit + + # scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/k= rb5.tab + # rm /root/libvirt-foo-example.tab + +Any client application wishing to connect to a Kerberos enabled libvirt +server merely needs to run ``kinit`` to gain a user principal. This may +well be done automatically when a user logs into a desktop session, if +PAM is set up to authenticate against Kerberos. diff --git a/docs/meson.build b/docs/meson.build index f80a08112e..0179a68908 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'auth', 'bindings', 'bugs', 'cgroups', @@ -107,6 +106,7 @@ docs_rst_files =3D [ 'apps', 'architecture', 'auditlog', + 'auth', 'best-practices', 'ci', 'coding-style', --=20 2.29.2 From nobody Sun May 5 18:42:52 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) client-ip=63.128.21.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 63.128.21.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=1615549536; cv=none; d=zohomail.com; s=zohoarc; b=lbtm/I/h7Fqt6Z+sTyFOGfWN632bc1DwdIBFMVokO/44uJ6kAxuv62qzckbxqjaKNpvpkzfG0/0sVYaCI2ihatdn9icxlYkQup6+AfWcug/SAtkJUPO3AF86gfEyLzVR2W+y27nNDcU3drr036roZclPRjjN4QXagEbi1qhJ6p0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549536; h=Content-Type:Content-Transfer-Encoding:Cc: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=li303RVJlG7kDFFKFQuFAflVMZ6osbQmodet3vDVpLI=; b=GPFF7tojb68Xj1GMuOy3RSh7q+tTtvjTwZ1MYFMJ0yK/tDupGFB8F4RmbJg4Azgh33h//U22c2ShCaQkpUwWIZrSnKN79En3l2zX9xTc5krggjQg1hwVJFzK11Cj8Xer6OGm1pSc7EDfSRsZ1OqrOhVTdEpQKtvNLGVYnk1gQvI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 63.128.21.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.zohomail.com with SMTPS id 1615549536242202.89116376409766; Fri, 12 Mar 2021 03:45:36 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-596-pNhSo7xAO3uFQKi5nvx99w-1; Fri, 12 Mar 2021 06:45:21 -0500 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 4D6AE100C61A; Fri, 12 Mar 2021 11:45:15 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 1548919C71; Fri, 12 Mar 2021 11:45:15 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id AFB32180223D; Fri, 12 Mar 2021 11:45:14 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhPxW024912 for ; Fri, 12 Mar 2021 06:43:25 -0500 Received: by smtp.corp.redhat.com (Postfix) id 18B9B60657; Fri, 12 Mar 2021 11:43:25 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6745160636; Fri, 12 Mar 2021 11:43:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549535; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=li303RVJlG7kDFFKFQuFAflVMZ6osbQmodet3vDVpLI=; b=WNLXNV+9A+XYsLqhs1zPtShbgLcngMEeQmG3ZzhGGxe2dasSS5vl4c0SK0Qo9O2vcmMcaw cmgtWvjpAQ7vp2S6LNbhXRix/ymMruWQBZwrLkPUoaS+FmaH324WsBX9f7iFZnxNbAlSRZ dVa7Opcn2A0JyGfKYTtwuePcxDKPBpc= X-MC-Unique: pNhSo7xAO3uFQKi5nvx99w-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 8/9] docs: html.in: Convert bindings to rst Date: Fri, 12 Mar 2021 12:43:11 +0100 Message-Id: <2bd67315c6976baa321ac9a91db216abaf732365.1615549300.git.eskultet@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 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) Content-Type: text/plain; charset="utf-8" Signed-off-by: Erik Skultety Reviewed-by: Peter Krempa --- docs/bindings.html.in | 101 ------------------------------------------ docs/bindings.rst | 62 ++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 63 insertions(+), 102 deletions(-) delete mode 100644 docs/bindings.html.in create mode 100644 docs/bindings.rst diff --git a/docs/bindings.html.in b/docs/bindings.html.in deleted file mode 100644 index a1520707c5..0000000000 --- a/docs/bindings.html.in +++ /dev/null @@ -1,101 +0,0 @@ - - - - -

                Bindings for other languages and integration API modules

                - -

                - Libvirt supports C and C++ directly, and has bindings available - for other languages: -

                - -
                  -
                • - C#: Arnaud Champion develops - C# bindings. -
                  • -
                • - Go: Daniel Berrange develops - Go bindings<= /a>. -
                  • -
                • - Java: Daniel Veillard develops - Java bindings. -
                  • -
                • - OCaml: Richard Jones develops - OCaml bindings. -
                  • -
                • - Perl: Daniel Berrange develops - Perl bindings. -
                  • -
                • -

                  - PHP: Radek Hladik started developing - PHP bindings in 2010. -

                  -

                  - In February 2011 the binding development has been moved to the l= ibvirt.org website as - libvirt-php project. -

                  -

                  - The project is now maintained by Michal Novotny and it's heavily= based - on Radek's version. For more information, including - information on posting patches to libvirt-php, please refer - to the PHP bindings site. -

                  -
                  • -
                • -

                  - Python: Libvirt's python bindings are split to a - separate p= ackage - since version 1.2.0, older versions came with direct support for= the - Python language. -

                  -

                  - If your libvirt is installed as packages, rather than compiled - by you from source code, ensure you have the appropriate - package installed. -

                  -

                  - This is named libvirt-python on RHEL/Fedora, - python-libvirt - on Ubuntu, and may be named differently on others. -

                  -

                  - For usage information, see the - Python API bindings page. -

                  -
                  • -
                • - Ruby: Chris Lalancette develops - Ruby bindings. -
                  • -
                - -

                - Integration API modules: -

                - -
                  -
                • - D-Bus: Pavel Hrdina develops - D-Bus API. -
                  • -
                - -

                - For information on using libvirt on Windows - please see the Windows support page. -

                - -

                - Support, requests or help for libvirt bindings are welcome on the - mai= ling list, - as usual try to provide enough background information and make sure - you use recent version, see the help page. -

                - - - diff --git a/docs/bindings.rst b/docs/bindings.rst new file mode 100644 index 0000000000..c5b6b94519 --- /dev/null +++ b/docs/bindings.rst @@ -0,0 +1,62 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D +Bindings for other languages and integration API modules +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Libvirt supports C and C++ directly, and has bindings available for +other languages: + +- **C#**: Arnaud Champion develops `C# bindings `__. + +- **Go**: Daniel Berrange develops `Go + bindings `__. + +- **Java**: Daniel Veillard develops `Java bindings `__. + +- **OCaml**: Richard Jones develops `OCaml + bindings `__. + +- **Perl**: Daniel Berrange develops `Perl + bindings `__. + +- **PHP**: Radek Hladik started developing `PHP + bindings `__ in 2010. + + In February 2011 the binding development has been moved to the + libvirt.org website as libvirt-php project. + + The project is now maintained by Michal Novotny and it's heavily + based on Radek's version. For more information, including information + on posting patches to libvirt-php, please refer to the `PHP + bindings `__ site. + +- **Python**: Libvirt's python bindings are split to a separate + `package `__ since version + 1.2.0, older versions came with direct support for the Python + language. + + If your libvirt is installed as packages, rather than compiled by you + from source code, ensure you have the appropriate package installed. + + This is named **libvirt-python** on RHEL/Fedora, + `python-libvirt `__ + on Ubuntu, and may be named differently on others. + + For usage information, see the `Python API bindings `__ + page. + +- **Ruby**: Chris Lalancette develops `Ruby + bindings `__. + +Integration API modules: + +- **D-Bus**: Pavel Hrdina develops `D-Bus API `__. + +For information on using libvirt on **Windows** `please see the Windows +support page `__. + +Support, requests or help for libvirt bindings are welcome on the +`mailing list `__, +as usual try to provide enough background information and make sure you +use recent version, see the `help page `__. diff --git a/docs/meson.build b/docs/meson.build index 0179a68908..f4b29a2e59 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -32,7 +32,6 @@ docs_assets =3D [ =20 docs_html_in_files =3D [ '404', - 'bindings', 'bugs', 'cgroups', 'compiling', @@ -107,6 +106,7 @@ docs_rst_files =3D [ 'architecture', 'auditlog', 'auth', + 'bindings', 'best-practices', 'ci', 'coding-style', --=20 2.29.2 From nobody Sun May 5 18:42:52 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.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 216.205.24.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=1615549511; cv=none; d=zohomail.com; s=zohoarc; b=cgi2aAEuohCGJXB2/0vREuTuswv41RgKCSw/DqenwaCu4/CDwBqH2nKeM9g5CcxsJf5fsrF3TXEFC7UvFiyGfrE44m1FUnrTJLCmki58wMDcRlco8cvvkq158p7Tbd6GU1wxSleVr+04CroYaYtnUTHYTbeN7h4RawulJY/y7ck= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1615549511; h=Content-Type:Content-Transfer-Encoding:Cc: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=R2w+0Kwx9MDb3qoZhSLOikQrKxIfabBcKWKhHXy5mD8=; b=fGCyei3oy/hDcjgwF//ETuB4AyzWo7dW0yFsxDJN7q1U/Gbu9GPcudhLE/iB8MD1pkC+jWDWcR1fGd9Ik94ea/j/qnVwqSS5n2h0z+e46nlbZsAtoNKTC+QlHzOC4t2QUrZElbFIX+Wa8B9HFqD3UfJxcoa2yApawjTf/e+4qYE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [216.205.24.124]) by mx.zohomail.com with SMTPS id 1615549511167171.28662880331524; Fri, 12 Mar 2021 03:45:11 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-159-0rlmdD82PsWiAsfnFqxdMg-1; Fri, 12 Mar 2021 06:45:06 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 0229A1084C83; Fri, 12 Mar 2021 11:45:01 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D38F160636; Fri, 12 Mar 2021 11:45:00 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 8C4DC1801241; Fri, 12 Mar 2021 11:45:00 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 12CBhQ1p024920 for ; Fri, 12 Mar 2021 06:43:26 -0500 Received: by smtp.corp.redhat.com (Postfix) id 1916E60636; Fri, 12 Mar 2021 11:43:26 +0000 (UTC) Received: from nautilus.redhat.com (unknown [10.40.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTP id 683CC19813; Fri, 12 Mar 2021 11:43:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1615549510; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=R2w+0Kwx9MDb3qoZhSLOikQrKxIfabBcKWKhHXy5mD8=; b=jUlXAL9vShW+UsZKO03/T7VdwbKPfyWz3FUmjQ/d6W7obxTX/i6kn3fbTvSJDH/dQyl0c1 7TBQkUAkEKDQAP0VXdM3EXOl967OIp05lCbsGuaBHROOT9cIZR2hqX8ORz2tSQv4QXebKE pfPe8o50aJMTgDh+qVfIGFJjh1jzoxc= X-MC-Unique: 0rlmdD82PsWiAsfnFqxdMg-1 From: Erik Skultety To: libvir-list@redhat.com Subject: [libvirt PATCH 9/9] docs: html.in: Convert 'compiling' to rst Date: Fri, 12 Mar 2021 12:43:12 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-loop: libvir-list@redhat.com Cc: eskultet@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 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) Content-Type: text/plain; charset="utf-8" Signed-off-by: Erik Skultety Reviewed-by: Peter Krempa --- docs/compiling.html.in | 115 ----------------------------------------- docs/compiling.rst | 95 ++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 96 insertions(+), 116 deletions(-) delete mode 100644 docs/compiling.html.in create mode 100644 docs/compiling.rst diff --git a/docs/compiling.html.in b/docs/compiling.html.in deleted file mode 100644 index df6074780f..0000000000 --- a/docs/compiling.html.in +++ /dev/null @@ -1,115 +0,0 @@ - - - - -

                libvirt Installation

                - -
                  - -

                  Compiling a release tarball

                  - -

                  - libvirt uses the standard setup/build/install steps and mandates - that the build directory is different from the source directory: -

                  - - 
                  -$ xz -dc libvirt-x.x.x.tar.xz | tar xvf -
-$ cd libvirt-x.x.x
-$ meson build
                  - -

                  - The meson script can be given options to change its default - behaviour. -

                  - -

                  - To get the complete list of the options run the following command: -

                  - - 
                  -$ meson configure
                  - -

                  - When you have determined which options you want to use (if any), - continue the process. -

                  - -

                  - Note the use of sudo with the ninja install command - below. Using sudo is only required when installing to a location yo= ur - user does not have write access to. Installing to a system location - is a good example of this. -

                  - -

                  - If you are installing to a location that your user does have = write - access to, then you can instead run the ninja install command - without putting sudo before it. -

                  - - 
                  -$ meson build [possible options]
-$ ninja -C build
-$ sudo ninja -C build install
                  - -

                  - At this point you may have to run ldconfig or a similar utili= ty - to update your list of installed shared libs. -

                  - -

                  Building from a GIT checkout

                  - -

                  - The libvirt build process uses Meson build system. By default when - the meson is run from within a GIT checkout, it - will turn on -Werror for builds. This can be disabled with - --werror=3Dfalse, but this is not recommended. -

                  - -

                  To build & install libvirt to your home - directory the following commands can be run: -

                  - - 
                  -$ meson build --prefix=3D$HOME/usr
-$ ninja -C build
-$ sudo ninja -C build install
                  - -

                  - Be aware though, that binaries built with a custom prefix will not - interoperate with OS vendor provided binaries, since the UNIX socket - paths will all be different. To produce a build that is compatible - with normal OS vendor prefixes, use -

                  - - 
                  -$ meson build -Dsystem=3Dtrue
-$ ninja -C build
-
                  - -

                  - When doing this for day-to-day development purposes, it is recommend= ed - not to install over the OS vendor provided binaries. Instead simply - run libvirt directly from the source tree. For example to run - a privileged libvirtd instance -

                  - - 
                  -$ su -
-# service libvirtd stop  (or systemctl stop libvirtd.service)
-# /home/to/your/checkout/build/src/libvirtd
-
                  - -

                  - It is also possible to run virsh directly from the build tree - using the ./run script (which sets some environment variables): -

                  - - 
                  -$ pwd
-/home/to/your/checkout/build
-$ ./run ./tools/virsh ....
-
                  - - diff --git a/docs/compiling.rst b/docs/compiling.rst new file mode 100644 index 0000000000..62519b6bdb --- /dev/null +++ b/docs/compiling.rst @@ -0,0 +1,95 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +libvirt Installation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Compiling a release tarball +--------------------------- + +libvirt uses the standard setup/build/install steps and mandates that +the build directory is different from the source directory: + +:: + + $ xz -dc libvirt-x.x.x.tar.xz | tar xvf - + $ cd libvirt-x.x.x + $ meson build + +The *meson* script can be given options to change its default behaviour. + +To get the complete list of the options run the following command: + +:: + + $ meson configure + +When you have determined which options you want to use (if any), +continue the process. + +Note the use of **sudo** with the *ninja install* command below. Using +sudo is only required when installing to a location your user does not +have write access to. Installing to a system location is a good example +of this. + +If you are installing to a location that your user *does* have write +access to, then you can instead run the *ninja install* command without +putting **sudo** before it. + +:: + + $ meson build [possible options] + $ ninja -C build + $ sudo ninja -C build install + +At this point you **may** have to run ldconfig or a similar utility to +update your list of installed shared libs. + +Building from a GIT checkout +---------------------------- + +The libvirt build process uses Meson build system. By default when the +``meson`` is run from within a GIT checkout, it will turn on -Werror for +builds. This can be disabled with --werror=3Dfalse, but this is not +recommended. + +To build & install libvirt to your home directory the following commands +can be run: + +:: + + $ meson build --prefix=3D$HOME/usr + $ ninja -C build + $ sudo ninja -C build install + +Be aware though, that binaries built with a custom prefix will not +interoperate with OS vendor provided binaries, since the UNIX socket +paths will all be different. To produce a build that is compatible with +normal OS vendor prefixes, use + +:: + + $ meson build -Dsystem=3Dtrue + $ ninja -C build + + +When doing this for day-to-day development purposes, it is recommended +not to install over the OS vendor provided binaries. Instead simply run +libvirt directly from the source tree. For example to run a privileged +libvirtd instance + +:: + + $ su - + # service libvirtd stop (or systemctl stop libvirtd.service) + # /home/to/your/checkout/build/src/libvirtd + + +It is also possible to run virsh directly from the build tree using the +./run script (which sets some environment variables): + +:: + + $ pwd + /home/to/your/checkout/build + $ ./run ./tools/virsh .... diff --git a/docs/meson.build b/docs/meson.build index f4b29a2e59..e816953bf4 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -34,7 +34,6 @@ docs_html_in_files =3D [ '404', 'bugs', 'cgroups', - 'compiling', 'contact', 'contribute', 'csharp', @@ -111,6 +110,7 @@ docs_rst_files =3D [ 'ci', 'coding-style', 'committer-guidelines', + 'compiling', 'daemons', 'developer-tooling', 'formatbackup', --=20 2.29.2